Estilos de documentação de comentários / no código

Esta pode ser uma pergunta estúpida, mas está na minha cabeça há um tempo e não consigo encontrar uma resposta decente em nenhum outro lugar.

Eu tenho um professor que diz que devemos listar explicitamente cada parâmetro com uma descrição, mesmo se houver apenas um. Isso leva a muita repetição:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Ao escrever a documentação em código, você é detalhado?

Para iniciantes, concordo que a linha "Function:" no seu exemplo é completamente redundante. Também foi minha experiência que as pessoas ensinaram na escola a adicionar esse tipo de comentário e continuar adicionando esse tipo de comentário em seu código de produção.

Bons comentários não repetem o que está no código. Eles respondem à pergunta "Por quê?" em vez de "o quê?" ou como?" Eles cobrem as expectativas sobre as entradas, bem como como o código se comportará sob certas condições. Eles abordam por que o algoritmo X foi escolhido em vez do algoritmo Y. Em resumo, exatamente as coisas que não seriam óbvias para outra pessoa ¹ ao ler o código.

^{1: Alguém mais familiarizado com o idioma em que o código está escrito. Não escreva comentários para ensinar, comente para complementar as informações.}

Várias linguagens possuem recursos de geração de documentos API como Ruby, Java, C # e C ++ (por meio de uma ferramenta de linha de comando). Quando você pensa dessa maneira, torna a escrita dos documentos da API muito mais importante. Afinal, ele responde à pergunta "como eu faço ...?" Portanto, não farei nada repetitivo como Function: MyFunctionquando o nome da função é claro para todo mundo ver. As ferramentas de geração de documentos da API são inteligentes o suficiente para fazer isso por mim. No entanto, os seguintes detalhes são úteis, particularmente em métodos / funções públicos:

• Resumo (o que faz e, quando relevante, um resumo de como usá-lo)
• Lista de parâmetros e o que é esperado
• Qual será o valor de retorno (saída)
• Quaisquer exceções que possam ser lançadas explicitamente e por que

Elas podem se tornar ferramentas de referência úteis quando você está tentando depurar código. Muitos IDEs também usarão os documentos da API nas dicas de ferramentas à medida que você passa o mouse sobre o nome da função.

Se é um idioma sem esses recursos, os comentários ajudam, mas não tanto.

Se for um método público de API, sim, você deve fornecer documentação detalhada, especialmente sobre parâmetros e comportamento esperado. Muitas pessoas acham que isso pode ser relaxado para métodos / funções particulares, YMMV.

No geral, prefiro escrever código limpo (pequenos métodos / funções que fazem uma coisa e uma coisa bem) com nomes de variáveis ​​sensíveis. Isso faz com que grande parte do seu código se autodocumente. No entanto, certamente sempre documento casos extremos, usos de simultaneidade e algoritmos complexos.

Em resumo, pense em si mesmo como um pouco pior para o desgaste às 3 da manhã, daqui a três meses. Você agradecerá seus documentos públicos impressionantes, em vez de descobrir o que significa parâmetro (sinalizador booleano) ...

É semelhante à maneira como a maioria das estruturas -Doc analisa a documentação em código (JavaDoc, PHPDoc etc.).

No Java, gerado automaticamente pelo IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Este é o mesmo formato usado para gerar a documentação para os recursos de idioma interno - Exemplo: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Esse formato é bastante útil porque mostra claramente a qualquer usuário de terceiros como fazer interface com seu código. Se suas funções são métodos particulares usados ​​apenas internamente, pode ser um pouco inútil - mas eu acho que seu professor está tentando fazer com que você pratique uma boa prática até que todos tenham experiência em fazer essa distinção.

O único bit que frequentemente acho redundante é a descrição do retorno - geralmente é quase idêntica à descrição do meu método.

Há dois propósitos para Comentários:

1. Eles servem para lembrá-lo rapidamente do que seu código faz quando você volta meses / anos depois. Dessa forma, você não precisa reler e analisar seu código para atualizar sua memória.
2. Eles transmitem para outras pessoas que podem estar lendo ou trabalhando com seu código o que seu código está fazendo.

É claro que existem muitas maneiras diferentes de abordar isso, mas quanto mais completo e consistente você for, melhor. Os comentários eficazes levam tempo para aprender, assim como a programação eficaz. Lembre-se de que é difícil ver o ponto dos comentários na escola, pois nada em que você está trabalhando é grande o suficiente para realmente justificá-lo, mas eles estão apenas tentando apresentá-lo a você. E, geralmente, a maneira como você ensina a fazê-lo é o estilo de seu professor, e não de qualquer forma qualquer padrão. Desenvolva o que funciona para você. E lembre-se ... existe um comentário estúpido! :) Exemplo:

a += 1; //adds 1 to the value in a

Realmente? Obrigado! ri muito

Eu gosto da documentação do site PHP, então uso algo semelhante nos meus comentários embutidos e na sintaxe do PHPDoc. Veja o exemplo abaixo.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

E, como o @Larry Coleman disse, os comentários incorporados devem dizer por que você fez algum código.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Se estiver a serviço da geração do Doc, comentários detalhados (embora irritantes) provavelmente são uma coisa boa. Embora você precise definir como meta da equipe manter-se atualizado sobre os comentários e mantê-los atualizados.

Se for apenas o estilo de comentários, eu teria problemas com isso. Comentários excessivos podem prejudicar o código tanto quanto ajudar. Não consigo contar o número de vezes que encontrei comentários no código que estavam desatualizados e, como resultado, enganosos. Eu geralmente ignoro os comentários agora e me concentro na leitura do código e nos testes do código para entender o que ele faz e qual é a intenção.

Prefiro ter um código claro e não comentado, conciso . Faça-me alguns testes com asserções ou métodos descritivos e estou feliz e informado.