Como “auto-documentado” código pode ser sem ser chato? [fechadas]

Question

Eu não sei o que são as melhores práticas aqui, mas vejo frequentemente abreviado nomes de variáveis, especialmente quando o escopo é pequena. Então (para usar exemplos simples de Ruby) em vez de def add_location(name, coordinates), vejo coisas como def add_loc(name, coord) e eu poderia até ver algo como def add_loc(n, x, y). Eu imagino que nomes mais longos pode cansar uma pessoa quando eles estão acostumados a ver abreviaturas.

O detalhamento ajuda a legibilidade, ou faz os olhos de todos apenas ferido? -Do pessoas preferem abreviaturas e nomes encurtados sobre nomes mais longos?

Answer 1

Pessoalmente, eu preferiria ver nomes mais longos que realmente significar alguma coisa sem ter de determinar o contexto em primeiro lugar. Claro, variáveis ??que não emprestam significado real, como contadores, eu ainda uso pequenos nomes de variáveis ??sem sentido (como i ou x), mas caso contrário verbosidade é a clareza a maior parte do tempo. Isto é especialmente verdadeiro com APIs públicas.

Isto pode ser levado muito longe, no entanto. Eu vi algum código VB no passado que maneira ridícula. Moderação como tudo o mais!

Answer 2

Eu realmente usar longo nomes de variáveis ??o tempo todo, depois de todos os IDEs modernas e texteditors têm conclusão, então não há nada de errado em usar index vez se eu. A única exceção que eu tenho é quando se lida com coordenadas b / c x e y fazer mais sentido lá.

Answer 3

Nunca abbr.

Answer 4

Uma variável deverá ser dada a mais curta possível nome que transmite adequadamente a sua finalidade.

Over-verbosidade tende a esconder sintaxe e sintaxe é importante.

Através de um programa inteiro (ou application / sistema) variáveis ??devem ser nomeados com estilo consistente e coisas semelhantes devem ser nomeados de forma semelhante. Se uma convenção existe dentro da comunidade linguística, deve ser observado (por isso não camelCaseRubyVariableNames não) a menos que haja alguma razão convincente para não fazê-lo.

Das abreviações, se utilizados, devem ser aplicadas de forma consistente em todos os lugares e se específica de domínio, deve ser registrado em algum lugar. Se alguém está indo para gastar qualquer quantidade útil de tempo com o código, em seguida, eles vão aprender mais rápido.

Se você precisa combinar até cinco ou seis palavras para nomear uma variável, então eu sugiro que você pode estar olhando para um código cheiro ea rotina que você está trabalhando podem se beneficiar de um pouco de trabalho.

Na maior parte, porém, se você está ciente das armadilhas e realmente pensar sobre o que você está escrevendo, as chances são de que seu código será razoável. Imagine-se descrevendo a função que está a trabalhar para um novo colega -. A menos que você acha que precisa dizer, melhor o código, provavelmente é

Answer 5

Tente ler o seu próprio código de 1 ano mais tarde. Você verá tanto o valor de nomes de variáveis ??auto documentar, e o valor dos comentários de código (e especialmente o valor de código limpo)

Quando você pega alguém código de outra fonte e você não entender isso, é fácil pensar "Bem, ele não é tão bom programador como eu sou" Mas quando você percebe que seu próprio código é difícil de ler você vai como: " o que era eu thinkng? "

No detalhamento longo prazo, ajuda a manutenção. Para breve um script de linha, você ainda pode usar "setLocNm" em vez de setLocationName "

Qualquer tolo pode escrever código que um computador possa entender. Bons programadores escrever código que os seres humanos podem entender. -Martin Fowler

Answer 6

Pessoalmente, acho verbosidade uma coisa boa, mas é fácil de ser excessivamente detalhado também, que é uma coisa ruim. Há um equilíbrio, e abreviaturas pode entrar em esse equilíbrio também.

Estas são as minhas regras gerais:

• Iterators pode ser uma letra, ou seja. i, j, k, etc.
• Outras variáveis ??palavra um como alterna boolean, o que você nunca são abreviados, ie. installing, done, etc.
• Diversas variáveis ??palavras e nomes de função são candidatos a sigla, mas apenas se eles estão começando a ficar ridiculamente longo (digamos, 20-25 + caracteres). abreviatura inteligente é a chave aqui. function => func por exemplo, mas nunca fun, f, ou functi

Answer 7

Eu folheei as respostas, mas eu não ver se o seguinte é coberto. Aqui vai ...

Se você abreviar ou sendo detalhado, apenas garantir que você tenha usado sem mais palavras do que o necessário e o significado é maldito óbvio.

No entanto, mesmo após esta filtragem se os seus identificadores olhar detalhado, você tem uma falha em seu projeto.

def initialize_report_template()
end

deveria ter sido ...

class ReportTemplate
    def initialize()
    end
end

Answer 8

Nomes mais longas são muito melhor. Você menciona que você vê frequentemente nomes abreviados em pequenos âmbitos. Quem vai dizer o escopo permanecerá pequeno como o software cresce?

Claro, XCoordinateForCurrentLocationOfSelf é um nome ridículo, por isso só ser razoável. Especialmente se você está andando em um projeto que você não tenha trabalhado antes, você vai agradecer quem usado função descritiva e nomes de variáveis.

Answer 9

Eu acho que é ok para abreviar quando o nome prejudicaria a legibilidade ou apenas ser redundante.

Exemplo 1:. Um argumento a um método em que o tipo Allready transmite toda a informação necessária

Exemplo 2: Uma variável que será usar uma grande quantidade de uma forma óbvia

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Exemplo 3: abreviaturas Idiomatic. i, j, k tem sido mencionado proprietária. "Sb" acima é um em nosso código, e cada equipe, provavelmente, tem mais um par.

Answer 10

Aim para mais curto em vez de mais tempo, mas o entendimento leitor deve trunfo preguiça de digitar cada vez.

Como já foi dito, o comprimento nome da variável não deve lógica obscuro ou algoritmo. Por exemplo, em aritmética, nós escrevemos

( 1 + 5 ) * 3 = 18

em vez de

three multiplied by the sum of one and five equals eighteen

porque estamos tentando chamar a atenção para outras coisas que não a clareza dos elementos envolvidos na expressão.

Eu tendem a manter as variáveis ??de um a três palavras, abreviando só quando eu exceder 24 caracteres ou menos. A menos freqüentemente uma variável é usada, o mais provável Estou a sentir-se livre para fazer o nome da variável tempo. variáveis ??mais freqüentemente utilizado farei mais curto.

Answer 11

Max Kanat-Alexander, o arquiteto-chefe de Bugzilla, diz que esta em seu blog:

próprio Código deve ocupar espaço em proporção com a quantidade de significado que ele tem.

Basicamente, pequenos símbolos que significam muito código make difícil de ler. Muito longo nomes que não significam muito também fazer código difícil de ler. A quantidade de o que significa eo espaço ocupado deve estar intimamente relacionados entre si.

http://www.codesimplicity.com/post/readability-and -naming-coisas /

É um post muito perspicaz sobre nomear as coisas. Exorto todos a lê-lo!

Answer 12

A única vez que eu aceito abreviaturas é para variáveis ??locais que só estão no escopo para um pequeno período de tempo.

O que significa que deve estar entrando em escopo com um método muito legível ou construtor.

Answer 13

Eu concordo com Kilhoffer; Eu prefiro ver os nomes de variáveis ??descritivos em quase todos os contextos. Vou abreviar se meus nomes de variáveis ??são mais de 20 caracteres ou menos, geralmente com palavras o nome da variável (por exemplo: "SomeVeryLongVarValue").

Claro, eu também usar a notação húngara sempre que posso, então eu poderia muito bem estar no outro extremo do acampamento de tentar fazer meus variáveis ??nomes excessivamente descritivo, dependendo da sua perspectiva.

Answer 14

Eu estou indo provavelmente ser completamente vaiado, mas eu queria ter certeza que este ponto de vista foi ouvido.

Enquanto nomes de variáveis ??mais longos podem ser mais descritivo eles podem começar a mire a intenção original do programa. Eu sinto que em elementos de API que é importante ter nomes claros e significativos no contexto de que eles serão usados.

Dentro de cada função ou método esta é muitas vezes uma história diferente. Eu tento escrever menos e mantê-lo muito concisa. Isto é conhecido como programação espartano al uma Mr. Atwood e este exemplo bacana . Sim, o exemplo é claramente manipuladas, mas ele faz demonstrar como tendo um pouco menos cerimônia realmente pode fazer a leitura do programa mais fácil.

Boa sorte.

Answer 15

Durante a programação você está usando a sintaxe para que os seres humanos podem lê-lo, o comprimento dos nomes de variáveis, métodos, etc ... são realmente irrevelant.

O mais detalhado melhor normalmente, com um bom ambiente de desenvolvimento que você deve ter a conclusão do código de qualquer maneira, então você pode simplesmente clicar em "add_L" + TAB para terminar a chamada de método.

Answer 16

Eu acho que o principal problema com abreviaturas é que nem todos os abrevia pessoas na mesma maneira , então quando você trabalhar com muitas pessoas que só pode aumentar a probabilidade de erro quando a codificação. Por exemplo, se você tem uma constante que pode ser chamado SOMETHING_INTERFACE, talvez alguns desenvolvedores iria abreviá-lo como SOMETHING_INTFACE, outros como SOMETHING_IFACE ou SOMETHING_IF, SMTHING_IFACE ...

Com apenas duas palavras que você pode ter, pelo menos, meia dúzia de mais ou menos "lógica" possíveis abreviaturas, então eu acho que é melhor na maioria dos casos para escrever, sem abreviaturas e com mais razões, se você quiser ter auto código -docummented.

Nomes muito longos podem ser por vezes irritantes, mas também pode ser abreviado em âmbitos muito locais, utilizando variáveis ??auxiliares.

Answer 17

A maioria das pessoas vista ler, não é mais necessário para ler uma palavra em seguida, para ler uma letra individual. Então, sempre use nomes significativos. Será que eles têm que ser descrições completas 7 palavra, não, mas eles precisam ser mais suficiente para entender.

Eu poderia aceitar add_loc (nome, coord), como eles são longos o suficiente eu posso dizer que eles são. Em add_loc (n, x, y), que se oporia a 'n' em vez do nome. Eu poderia viver com X e Y como estes são os nomes aceitos de coordenadas.

Para alguém não familiarizado com sistemas de coordenadas que eu poderia ver onde add_location (nome, coordenadas) seria mais significativa.

Em caso de dúvida, use nomes mais longos.

Answer 18

"É OK para descobrir mistérios de assassinato, mas você não deve precisar de descobrir o código Você deve ser capaz de lê-lo.". - Steve C. McConnell

Dito isto, se você acha que nomes de variáveis ??você nem ninguém necessidades excessivamente explícitas e assim por diante, fique à vontade para abreviá-los.

Answer 19

Eu sugiro dar uma abordagem minimalista. Use um pouco quanto possível, assegurando as suas estadias de código claro, conciso e direto ao ponto.

Answer 20

Fora de coisas escopo como constantes e variáveis ??globais devem ter nomes descritivos longo. Às vezes, um nome muito longo fará com que seja "cheiro" apenas o suficiente para sinalizar a sua presença como sendo indesejada. Isso é uma coisa boa becuase vai 1 - fazer as pessoas evitá-lo, 2 -. Aumentar a pressue refatorar o código para fazer isso ir embora