Melhor maneira de escrever comentários no código [closed]

4

Eu queria saber como se deve escrever comentários no código. Quero dizer, um comentário deve ser descritivo do que é feito no código, como: //we have got array, now we iterate over it. code to iterate array

ou deveria estar dizendo o que devemos fazer aqui. como um pedido, como: //we have got array, iterate over it. code to iterate array

    
por rahil008 15.04.2016 / 09:57
fonte

5 respostas

11

Visão geral do que é o código. Pode ser óbvio quando você o escreve, mas não dois anos depois, então anote quando este código é usado na aplicação, porque é usado e assim por diante. Como "este código lida com a situação em que um usuário preenche um formulário reclamando de pacotes devolvidos perdidos no post". Responde a pergunta "o que diabos é esse código para".

Se não for óbvio, uma visão geral de alto nível de como o código funciona.

Comentários em arquivos de cabeçalho (ou em locais onde são extraídos automaticamente) para que, para cada função pública, um leitor saiba o que faz e por que deve ser chamado sem se referir ao código-fonte.

Especialmente para funções virtuais: Comentários em arquivos de cabeçalho que essa função, incluindo substituições, deve fazer. Para funções não virtuais, os comentários são uma conveniência, evitando que eu leia o código-fonte. Para funções virtuais, não há código-fonte .

Comentários que informam outros desenvolvedores quando você faz algo que parece estranho. Há lugares onde meu código contém algumas linhas que parecem um absurdo absoluto e, em seguida, há um comentário "Funciona em torno de um bug na biblioteca XYZ".

Comentários explicando o que o código faz em termos do problema que é resolvido. Como "encontre todos os clientes que compraram itens no valor de menos de US $ 100 no último ano e fizeram mais de três retornos" - isso pode não ser óbvio no código.

"Temos matriz, iterar sobre isso", como um comentário para o código iterar em uma matriz é um disparate. Eu posso ver que você está iterando, eu não preciso de um comentário para isso. Diga-me o que a iteração está realmente fazendo.

    
por 15.04.2016 / 10:19
fonte
40

Nem Comentários não devem descrever o que faz (no mesmo nível de abstração que o próprio código), mas apenas por que ele faz alguma coisa

Não leve isso muito literalmente, isso é uma diretriz, se você escrever um breve resumo o que um código mais longo irá fazer, isso pode ser aceitável. No entanto, comentários descrevendo coisas óbvias como "isso é uma iteração" devem ser evitados, eles não tornam o código mais legível ou compreensível, adicionam apenas desordem e violam o princípio DRY.

    
por 15.04.2016 / 10:03
fonte
29

Os comentários que você escreve são bons para o código de demonstração ao ensinar um novo idioma para iniciantes. Eles são o equivalente a "Veja Jane correr. Corra, Jane, corra!"

Mas em todas as outras configurações, eles não são apropriados. Todo programador habitual ficaria confuso, pensando "Huh? Por que você está me dizendo isso quando já está absolutamente óbvio o que está acontecendo? Há algo não óbvio acontecendo que eu esteja sentindo falta?"

Um autor de novela não escreve "Jane saiu de casa e caminhou rua abaixo, colocando sistematicamente um pé na frente do outro". Ele escreveu "Jane foi à loja de departamentos", ou até "quando Jane chegou na loja de departamentos, ela ..." ou apenas "Tendo terminado as compras, Jane relaxou ..."

Da mesma forma, um programador profissional não escreveria

// Iterate over the array
for(int x: ai) { ...

mas no máximo

// notify all observers
for(int x: ai) { ...

ou mesmo apenas

notifyObservers()

onde o código atual está oculto em uma sub-rotina com um nome significativo.

    
por 15.04.2016 / 10:08
fonte
4

Os comentários são para comunicar qualquer informação a futuros desenvolvedores que estejam usando ou mantendo o código, o que não é óbvio na leitura do código.

Ao escrever comentários, considere as situações enfrentadas por um novo desenvolvedor que não esteja familiarizado com seu código e com sua atual mentalidade.

Enquanto você está escrevendo código, normalmente você está fazendo muitas bolas na sua cabeça, tentando evitar possíveis armadilhas; e seus comentários devem refletir as coisas com as quais você está lidando, porque é mais provável que sejam informações que qualquer desenvolvedor futuro também precisará saber para evitar cometer erros. Por exemplo:

// A user could potentially type an invalid username here but we can't
// validate it yet because we need to support the legacy login format.

ou

// We don't know whether the server is available yet, but we don't care
// until the user does something which involves a message to the server.

ou

// Always use the FooFactory for creating Foo objects because it guarantees
// they will be initialised using the correct Config.

ou

// This calculation is only an approximation until the customer can 
// supply us with the correct logic, so we know it's wrong, but the
// customer confirmed they are happy with it as an interim measure. 

ou

// HACK: this function fixed a critical fault identified while on XYZ customer site.  
// This is currently in use by XYZ, it must be refactored into a generic solution ASAP.
// see ticket #12345 in the bugtracking system.

ou

// This function may fail if VehicleType==Train, but there are currently no 
// documented requirements or data for Trains, so there's no way to reliably test it.

Então, ao tentar decidir que tipo de comentário colocar em seu código, dê vários passos para trás a partir do próprio código e pense sobre todos os problemas que você enfrentou, as suposições que você fez, os compromissos que você fez etc.

Os comentários devem ser uma justificativa que capte "Por que escrevi esse código dessa maneira em particular neste momento específico?". A realidade é que o código geralmente nunca é 'terminado' , o código tende a evoluir constantemente, ele tende a ser limitado por questões do mundo real (prazos, demandas do cliente, orçamento, etc.). Por isso, sempre haverá verrugas e imperfeições que estão além do controle do desenvolvedor.

Seus comentários são o melhor lugar para documentar essas coisas - evite escrever longas redações, apenas mantenha a quantidade mínima de informações que podem alertar futuros desenvolvedores a não cometer erros, ou até mesmo deixe-os saber que você já considerou benefícios / limitações de sua solução (ou mesmo se você encontrou problemas potenciais com o código existente de outra pessoa e não conseguiu consertá-lo).

    
por 16.04.2016 / 12:45
fonte
1

Acho que a resposta para o seu exemplo específico é nenhuma das duas. Comentários não devem explicar o que o código faz. O CÓDIGO deve explicar o que o código faz. Os comentários nem mesmo devem explicar por que isso acontece, o que deve ser óbvio, mesmo com conhecimento de domínio leve ou com conhecimento técnico.

Esta segunda parte é difícil às vezes. Às vezes você encontra algum bug obscuro ou uma peculiaridade muito estranha em algum framework que está usando. O "código obviamente melhor" pode, na verdade, ser pior do que o atual código de aparência estranha, e nesses casos, é claro que é aceitável fazer uma exceção e adicionar um comentário explicando a situação.

Isso deve ser visto como um fracasso. É algo a ser evitado, porque, como outros aludiram, os comentários são em grande parte redundantes. O MUITO raramente realmente dá algum valor. Mas violar DRY não é a pior parte. A pior parte com comentários é que eles não são código, então eles não são executados e, portanto, o leitor não tem nenhuma prova de que o comentário tenha algo a ver com a realidade.

Os comentários envelhecem, eles têm erros, ficam órfãos, o autor pode estar errado, etc. Eles são notoriamente enganosos. Mesmo se você vir um comentário dizendo "este bloco de código faz X", você não pode realmente confiar que ele faz X sem olhar para ele.

Se você acha que a estrutura algorítmica de seu código é difícil de ver num piscar de olhos, a solução não é adicionar 20 comentários. É reestruturar / refatorar o código para que ele seja separado em pequenas unidades lógicas concisas com bons nomes de métodos. Use os padrões que todos nós aprendemos. Encapsular as coisas. Projete uma boa arquitetura, não cubra uma ruim, colando post-its em todo lugar.

EDIT: Só para esclarecer uma vez que algumas pessoas parecem ter interpretado mal: eu não estou dizendo que você nunca deve usar comentários. Eu estou dizendo que você realmente não deveria querer porque eles trazem muitos problemas. Estou dizendo que às vezes você precisa, mas deve tentar encontrar uma solução melhor.

    
por 15.04.2016 / 10:45
fonte