Quero ouvir de você algum conselho e experiência em escrever comentários em seu código. Como você os escreve da maneira mais fácil e informativa? Que hábitos você tem ao comentar partes do código? Talvez algumas recomendações exóticas?
Espero que esta pergunta colete os conselhos e recomendações mais interessantes para comentar, algo útil que todos possam aprender.
OK, eu vou começar.
Normalmente, não uso
/* */
comentários, mesmo quando preciso comentar muitas linhas.Vantagens : o código visualmente parece melhor do que quando você mistura essa sintaxe com comentários de uma linha. A maioria dos IDEs tem a capacidade de comentar o texto selecionado e geralmente o faz com sintaxe de uma linha.
Desvantagens : Difícil editar esse código sem o IDE.
Coloque "ponto" no final de qualquer comentário finalizado.
Por exemplo:
//Recognize wallpaper style. Here I wanted to add additional details int style = int.Parse(styleValue); //Apply style to image. Apply(style);
Vantagens : Coloque "ponto" apenas nos comentários que você terminou. Às vezes, você pode escrever informações temporais; portanto, a falta de "ponto" indica que você deseja retornar e adicionar algum texto adicional a esse comentário.
Alinhar texto nas enumerações, comentar parâmetros etc.
Por exemplo:
public enum WallpaperStyle { Fill = 100, //WallpaperStyle = "10"; TileWallpaper = "0". SizeToFit = 60, //WallpaperStyle = "6"; TileWallpaper = "0". Stretch = 20, //WallpaperStyle = "2"; TileWallpaper = "0". Tile = 1, //WallpaperStyle = "0"; TileWallpaper = "1". Center = 0 //WallpaperStyle = "0"; TileWallpaper = "0". };
Vantagens : Apenas parece melhor e visualmente mais fácil de encontrar o que você precisa.
Desvantagens : gastar tempo para alinhar e mais difícil para editar.
Escreva um texto no comentário que você não pode obter analisando o código.
Por exemplo, comentário estúpido:
//Apply style. Apply(style);
Vantagens : você terá um código claro e pequeno, com apenas informações úteis nos comentários.
fonte
:3,7 Align //
para alinhar comentários nas linhas 3-7.Respostas:
Algumas das afirmações abaixo são bastante pessoais, embora com alguma justificativa, e devem ser assim.
Tipos de comentário
Para a versão resumida ... Eu uso comentários para:
Leia abaixo os detalhes e (possivelmente obscuros) motivos.
Comentários finais
Dependendo do idioma, use comentários de uma linha ou comentários de várias linhas. Por que isso depende? É apenas uma questão de padronização. Quando escrevo código C, sou a favor do código ANSI C89 à moda antiga, por isso prefiro sempre
/* comments */
.Portanto, eu teria isso em C na maioria das vezes, e às vezes (depende do estilo da base de código) para idiomas com uma sintaxe semelhante a C:
O Emacs é legal e faz isso comigo
M-;
.Se o idioma suportar comentários de linha única e não for baseado em C, estarei mais inclinado a usar os comentários de linha única. Caso contrário, receio que agora tenha adquirido o hábito. O que não é necessariamente ruim, pois me força a ser conciso.
Comentários de várias linhas
Não concordo com o seu preceito usando comentários de linha única, pois isso é mais visualmente atraente. Eu uso isso:
Ou isso (mas não o faço com frequência, exceto em uma base de código pessoal ou principalmente em avisos de direitos autorais - isso é histórico para mim e vem da minha formação educacional. Infelizmente, a maioria dos IDEs estraga tudo ao usar o formato automático) :
Se for realmente necessário, gostaria de comentar em linha usando o que mencionei anteriormente para comentários finais, se fizer sentido usá-lo em uma posição final. Em um caso de retorno muito especial, por exemplo, ou para documentar
switch
ascase
instruções de a (raro, não uso a opção frequentemente), ou quando documento ramificações em umif ... else
fluxo de controle. Se esse não é um desses, geralmente um bloco de comentários fora do escopo que descreve as etapas da função / método / bloco faz mais sentido para mim.Eu as uso excepcionalmente, exceto se estiver codificando em um idioma sem suporte para comentários na documentação (veja abaixo); Nesse caso, eles se tornam mais prevalentes. Mas, no caso geral, é realmente apenas para documentar coisas que são destinadas a outros desenvolvedores e são comentários internos que realmente precisam se destacar. Por exemplo, para documentar um bloco vazio obrigatório como um bloco "forçado"
catch
:O que já é feio para mim, mas eu toleraria em algumas circunstâncias.
Comentários da documentação
Javadoc e cols.
Normalmente, eu os usava em métodos e classes para documentar versões que introduzem um recurso (ou alterá-lo), especialmente se for para uma API pública, e para fornecer alguns exemplos (com casos claros de entrada e saída e casos especiais). Embora, em alguns casos, um caso de unidade possa ser melhor para documentá-los, os testes de unidade não são necessariamente legíveis por humanos (não importa qual DSL você usa).
Eles me incomodam um pouco para documentar campos / propriedades, pois eu prefiro comentários finais para isso e nem toda estrutura de geração de documentação suporta comentários de documentação finais. O Doxygen faz, por exemplo, mas o JavaDoc não, o que significa que você precisa de um comentário importante para todos os seus campos. No entanto, posso sobreviver a isso, como as linhas Java são relativamente longas na maioria das vezes, então um comentário à parte me assustaria igualmente ao estender a linha além do meu limite de tolerância. Se Javadoc algum dia considerasse melhorar isso, eu ficaria muito mais feliz.
Código comentado
Eu uso a linha única por uma única razão, em idiomas do tipo C (exceto se estiver compilando para C estrito, onde eu realmente não os uso): para comentar coisas durante a codificação. A maioria dos IDEs terá alternado para comentários de linha única (alinhados no travessão ou na coluna 0), e isso se encaixa nesse caso de uso para mim. Usar a alternância para comentários com várias linhas (ou selecionar no meio das linhas, para alguns IDEs) tornará mais difícil alternar entre comentário / comentário com facilidade.
Mas, como sou contra o código comentado no SCM, isso geralmente é muito curto, porque vou excluir os pedaços comentados antes de confirmar. (Leia minha resposta a esta pergunta em "comentários editados por linha e SCMs" )
Estilos de comentário
Eu costumo escrever:
Uma nota sobre programação alfabetizada
Talvez você queira se interessar por programação alfabética , conforme apresentado neste artigo por Donald Knuth .
Como observação e exemplo: A estrutura JavaScript underscore.js , apesar da não conformidade com meu estilo de comentário, é um bom exemplo de uma base de código bem documentada e de uma fonte anotada bem formada - embora talvez não seja a melhor para usar como uma referência de API).
Estas são convenções pessoais . Sim, eu posso ser estranho (e você também). Tudo bem, desde que você siga e cumpra as convenções de código de sua equipe ao trabalhar com colegas ou não ataque radicalmente suas preferências e coabite bem. Faz parte do seu estilo, e você deve encontrar a linha tênue entre o desenvolvimento de um estilo de codificação que o define como codificador (ou como seguidor de uma escola de pensamento ou organização com a qual você tem uma conexão) e respeitar a convenção de um grupo por consistência .
fonte
Quando fui para a universidade, sempre fui ensinado a comentar todas as linhas de código e todos os cabeçalhos de métodos. Foi tocado / doutrinado a tal ponto que você o fez sem questionar. Tendo participado de várias equipes de desenvolvimento Agile em diferentes empresas, posso dizer que posso escrever um comentário uma vez na lua azul.
A razão para isso é dupla: primeiro, não devemos mais escrever métodos monolíticos longos que fazem 101 coisas diferentes; os nomes de classe, método e variável devem ser auto-documentados. Tome o seguinte método de login como exemplo.
Isso pode ser reescrito para algo que é muito mais legível e talvez reutilizável:
Você pode ver claramente no método de login o que está acontecendo. Você pode ver isso como um trabalho extra, mas seus métodos são pequenos e têm apenas um trabalho. Além disso, os nomes dos métodos são descritivos, portanto não há necessidade de escrever nenhum comentário no cabeçalho do método. Se você acabar com muitos métodos, isso indica que os métodos relacionados devem ser fatorados novamente em outro objeto, como um UserAuthenticationService, lembre-se de que um objeto deve ter apenas um trabalho.
Em segundo lugar, cada pedaço de código que você escreve, incluindo comentários, precisa ser mantido, quanto mais comentários você tiver, mais há para manter. Se você renomear uma classe ou uma variável, receberá um erro de compilação, mas se alterar a maneira como uma seção de código funciona ou removê-la e não atualizar nenhum comentário relacionado, não haverá erro de compilação e os comentários permanecerão causando confusão. .
Se você estiver escrevendo uma API, acredito que quaisquer interfaces, classes e enumerações voltadas para o público devem ter comentários de cabeçalho bem escritos para documentação.
fonte
Concentre-se menos no formato e mais no conteúdo. Por exemplo, os comentários no seu exemplo não me dizem nada de novo. Eles são piores do que inúteis, pois prejudicam a leitura do código, e comentários como esses são, na melhor das hipóteses, uma referência vaga ao que o programador original pensou que estava fazendo no momento em que o escreveu. Eu posso ver no exemplo de código que você está aplicando um estilo "apply (Style)", eu posso ler a fonte. Não consigo ler sua mente - por que você está fazendo isso é o que o comentário deve me dizer. por exemplo, em vez de
//Apply style.
Apply(style);
deveria estar
// Unlike the others, this image needs to be drawn in the user-requested style apply(style);
A maioria de nós trabalha em equipes com o código existente, formata da mesma forma que o resto da equipe, da maneira que já está sendo feita. Consistência de muito mais importante do que bonita.
fonte
Na medida do possível, escreva seu código de forma que os comentários sejam completamente estranhos. Adicione comentários apenas quando o código não puder ser escrito de forma a tornar óbvio um conceito importante.
fonte
Minha preferência é mantê-lo realmente simples. Eu evito todo tipo de formatação sofisticada. A principal razão para isso é que acho que o código fonte deve ser confortavelmente editável, mesmo com o editor de texto mais simples. Eu também nunca enrolei parágrafos de texto, mas deixei o editor fazer o invólucro suave (sem adição de novas linhas).
fonte
Costumo ver comentários como esse, e algumas ferramentas geram automaticamente dessa maneira:
Duas linhas a menos:
IDEs e editores, marginalmente acima do nível do bloco de notas, são capazes de detectar comentários e imprimi-los em uma cor diferente. Não há necessidade de decorar o início da linha com asteriscos.
Você ainda poupa alguns bytes se usar uma guia para recuo.
Se você não usar um editor sofisticado, que renderize o comentário em tom cinza, a grande quantidade de asteriscos funcionará como ênfase e atrairá sua atenção, que é o oposto da coisa certa a fazer: ficar para trás.
fonte
Aqui está um "antipadrão" que encontrei em todo o código do meu trabalho: O uso de comentários como um "log de alterações"; é para isso que serve o log no seu sistema de controle de versão. O código está cheio de coisas como:
e geralmente inclui o código antigo comentado (novamente, esse é o objetivo de um sistema VCS, portanto, não precisa estar no código após a gravação do novo código). Além disso, algo a evitar é repetir comentários como "Por que precisamos disso?" ou pior ainda, "Isso provavelmente deve ser renomeado" (porque existem ferramentas sofisticadas para renomear, portanto, no tempo que você levou para escrever esse comentário, você poderia ter renomeado a coisa). Mais uma vez, trato desses dois comentários regularmente, de acordo com:
fonte
fonte
Os leitores de código geralmente estão tentando responder a três perguntas:
Tudo o resto deve ser expresso no código. Como escrever prosa, isso é uma arte e requer muita prática. A única maneira de saber se o seu código é compreensível é conseguir que alguém o leia. Quando eles não entenderem algo, não o explique verbalmente. Melhore o código. Adicione comentários como último recurso.
Se eu vir "comprimento duplo", perguntarei "Qual é a unidade de medida?" Não adicione um comentário. Mude o nome da variável. Se eu vir um bloco de código e disser "o que isso faz?", Não adicione um comentário. Extraia uma função com um nome significativo. Se você não pode extrair uma função porque precisaria de 17 argumentos, refatorar o código.
fonte