Guia do iniciante para escrever comentários?

27

Existe um guia definitivo para escrever comentários de código, destinado a desenvolvedores iniciantes?

Idealmente, cobriria quando os comentários deveriam (e não deveriam) ser usados ​​e quais comentários deveriam conter.

Esta resposta :

Não comente o que está fazendo, mas por que está fazendo.

O WHAT é tratado por código limpo, legível e simples, com escolha adequada de nomes de variáveis ​​para suportá-lo. Os comentários mostram uma estrutura de nível superior ao código que não pode ser (ou é difícil de mostrar) pelo próprio código.

chega perto, mas é um pouco conciso para programadores inexperientes (uma expansão nisso com vários exemplos e casos extremos seria excelente, eu acho).

Atualização : além das respostas aqui, acho que essa resposta a outra pergunta é altamente relevante.

language-agnostic comments Cameron
fonte
Acho que estamos nos mudando rapidamente para um mundo em que as pessoas não comentam mais. Para melhor de (mais provável) para pior. Ágil.
MK01 14/11
1
@ MK: Se for esse o caso (eu concordo mais com esta resposta ), um guia explicando como não escrever comentários e por que eles devem ser evitados seria igualmente útil. De fato, quanto mais pontos de vista diferentes, melhor.
Cameron #
Eu acho que pequenos comentários para melhorar a velocidade de leitura de código são muito úteis e sempre serão. Não compro completamente o raciocínio de "comentário obsoleto", mesmo que sejam obsoletos, teriam valor histórico. Eu costumava trabalhar em uma base de código que ocasionalmente tinha comentários detalhados aqui e ali e nunca fui realmente mordido pelo fato de o comentário estar desatualizado.
MK01
veja também: “Comentários são um cheiro de código”
mosquito

Respostas:

38

Você deve estar ciente da maior fraqueza dos comentários: eles ficam obsoletos. Ou seja, à medida que o código muda, os desenvolvedores raramente atualizam os comentários para permanecer sincronizados com o código. Isso significa que você nunca pode confiar neles e ainda acaba lendo o código. Por esse motivo, seu código deve ser auto-documentado. Você deve escolher seus nomes de função e variável de forma que o código pareça uma prosa.

Portanto, não documente o que o código está fazendo. O código de auto-documentação deve cuidar disso. Documente POR QUE você está fazendo isso. Os WHYs geralmente são relacionados a regras de negócios ou arquitetura e não mudam frequentemente e ficam obsoletos o mais rápido possível no WHATs. Documentar casos extremos. Documentar exceções. Decisões de design de documentos. E o mais importante, documente as decisões de design que você considerou, mas decidiu não implementar (e documente POR QUE você decidiu não usá-las).


fonte
2
O último é muito importante. Às vezes, há um efeito colateral / bug na implementação da solução óbvia. Documentar por que você optou por usar outra solução impede o próximo desenvolvedor de reintroduzir o bug quando ele "corrige" sua solução aparentemente ruim.
CaffGeek
2
Outro ponto, meu primeiro trabalho considerou os comentários tão importantes quanto o código. Tente adquirir o hábito de ler comentários e o código ao revisar seus pares e tente insistir para que os comentários estejam atualizados sempre que possível. Isso ajuda a evitar que os comentários fiquem obsoletos e mantém as regras de negócios etc. documentadas em seu código atualizadas.
Eric Hydrick
10

Você deve ler o livro de código limpo de Robert C. Martin . Explica bem que, se você precisar de comentários, provavelmente não está codificando corretamente. Idealmente, seu código deve ser "com comentários próprios". O livro Clean Coder explica como fazer isso, para que os comentários não sejam necessários e descreveu bem como fazer comentários em situações em que é necessário. (Como explicar uma fórmula matemática complexa)

Prumo
fonte
Embora eu não queira tanto explicar uma fórmula matemática complexa como gostaria que ela seja escrita em notação matemática adequada (possivelmente TeX), com uma explicação de seu significado e fonte. Se você não entende a fórmula, não deve mexer com o código que a usa para calcular algum valor, pois é excepcionalmente provável que você estrague e introduza erros (sutis ou não).
um CVn
O código pode apenas dizer como , não por que ou por que não . Você precisa de comentários para isso.
7

O Code Complete, como mencionado, possui várias diretrizes para escrever comentários. Em resumo, é PDL e pode ser resumido como:

  1. Descreva sua intenção, não o que o código está fazendo. Evite descrever os detalhes da implementação, a menos que esteja usando algum truque ou implementações personalizadas. Por exemplo, usando bits de deslocamento para dividir, usando aritmética de ponteiro para acessar membros da classe ou usando um alocador de memória personalizado para alguns objetos em pool.

  2. Escreva o pseudo-código (isto é, os comentários) primeiro e depois o código real depois de terminar de descrever sua rotina / método / função. A linguagem usada é de alto nível, mas específica, portanto pode ser bastante detalhada

  3. Tenha uma idéia do que seu código está fazendo antes mesmo de escrevê-lo

  4. Tenha comentários o mais próximo possível do código real

O objetivo é evitar comentários longos e não relacionados que possam estar desatualizados, mas ter comentários refletindo a intenção e o objetivo do código. Usar um pseudo-código de alto nível também ajuda a esclarecer seu pensamento antes de escrever a implementação.

Há um link no GameDev.net [que explica PDL] [1], caso você não queira rastrear o livro.

Extrakun
fonte
5
Escreva o pseudo-código (isto é, os comentários) primeiro . Eu não poderia discordar mais. Não há melhor maneira de garantir que os comentários não correspondam ao código. Os codificadores novos (e o solicitante que pediu especificamente um guia para iniciantes) irão hackear e refatorar as funções centenas de vezes antes de ficarem satisfeitos com eles, o código será movido rapidamente, reescrito, reutilizado e no final, eles podem possui uma solução de trabalho elegante, mas não se parecerá com o pseudo-código inicial. Os comentários serão movidos e atualizados à medida que o código funcionar? Você pode apostar o seu doce bippy que não. Meus dois centavos.
Worrier binário
1
Além disso, comentários em pseudo-código informarão o que o código deve fazer. O código deve lhe dizer isso. O pseudo-código não informa por que o código está fazendo isso. -1 cara, desculpe, mas não posso concordar com o segundo ponto, os tempos mudaram.
Worrier binário
1
Para não discutir, mas mais explicações - o pseudo-código é explicar a intenção do código que você escreveu. Ou seja, o comentário não é sobre detalhes da implementação (como "Adicionar x ao topo da pilha"), mas sobre o que o código deve fazer (como "Fazer a janela aparecer na frente de todo o resto"). Como você apontou corretamente, você precisa mover os comentários com o código. Eu discordo do código, posso dizer o que o código está fazendo - o tempo todo. Mesmo se, um comentário útil / preciso (se eu conseguir escrever bem!) Vai muito longe. No final, ainda IMHO.
Extrakun
3
Um método ou função chamado showWindowOnTop(window)sempre será melhor do que um comentário da mesma natureza, tudo isso está desatualizado e é um péssimo conselho em 2012. 1) Nomes de funções / métodos descrevem a intenção, 2) pseudo-código é um exercício oco com cadeias de ferramentas modernas 3) testes dizer-lhe o que o código é suposto fazer antes de escrevê-lo, 4) código bem nomeado é melhor do que comentários que não correspondem código mal chamado
1

Minha sugestão seria escrever um código sem qualquer comentário e depois sair dele. Volte em um ano e leia. A parte que você não entende facilmente é a parte que deveria ter comentado.

Kevin
fonte
1
Hah, sim ;-) Este não é um conselho particularmente útil - talvez isso deva ter sido um comentário?
Cameron #
a parte que você não entende, deveria ter escrito em partes menores e com melhor nome. A principal razão pela qual os comentários são inseridos no código é que as funções / métodos são muito demorados e devem ser muitas partes menores de auto-documentação.
0

Eu realmente gosto de como Evan Todd resume sua visão sobre as únicas categorias de comentários úteis ( citando em seu blog ):

  • Comentários explicando o porquê, e não o que. Estes são os mais úteis.
  • Comentários com algumas palavras explicando o que o seguinte bloco gigante de código faz. Estes são úteis para navegação e leitura.
  • Comentários na declaração de uma estrutura de dados, explicando o que cada campo significa. Isso geralmente é desnecessário, mas às vezes não é possível mapear um conceito intuitivamente para a memória, e comentários são necessários para descrever o mapeamento.
Cameron
fonte