Comentário antes ou depois do código relevante [fechado]

Supondo que um comentário não se encaixe (ou não possa ir) na linha a que se aplica, deve-se escrever o comentário antes do código ou depois?

Bem, sempre que futuros leitores entenderem melhor o escopo do comentário. Em outras palavras, onde quer que a maioria dos programadores / roteiristas coloque esses comentários.

Então, onde a maioria dos programadores / scripts coloca um comentário: antes ou depois do código?

Se sua resposta se aplica apenas a idiomas específicos, indique quais.

E se você pode citar uma especificação ou guia aceito que suporte sua resposta, tanto melhor.

Gostaria de comentar em linha ou antes do código ao qual o comentário deve se aplicar. O sentido dos comentários é obter um entendimento básico do que o código faz, sem a necessidade de ler o próprio código. Portanto, faz muito mais sentido colocar os comentários antes do código que ele descreve.

A Microsoft diz que seria uma boa prática de programação iniciar procedimentos com um pequeno comentário. (Eles não mencionam comentários após os procedimentos) MSDN O link é sobre VisualBasic, mas se aplica à maioria das linguagens de programação que eu penso.

Prefiro que os comentários estejam acima do código a que se referem, faz mais sentido dizer a uma pessoa que está lendo o código sobre o que está por vir do que tentar se referir ao código anterior para explicar que algumas linhas de código bagunçadas corrigiram algum erro complicado então não toque.

Eu acho que o código geralmente é lido de cima para baixo. Se nada mais, a memória muscular me faria associar um comentário à próxima linha de código abaixo dela.

Normalmente, o comentário deve estar no topo da linha, seguindo o mesmo recuo que o trabalho. Por exemplo, comentários acima do corpo das funções e comentários de uma linha logo acima do início de um algoritmo crítico.

O motivo é que, quando alguém começa a lê-lo, torna-se uma pergunta óbvia: por que algo é feito dessa maneira; onde a pessoa não sabe até que ponto é preciso rolar para a resposta. Se estiver no topo, está ali para ver.

Então, onde a maioria dos programadores / scripts coloca um comentário: antes ou depois do código?

Em muitos anos de programação usando uma variedade de linguagens, não me lembro de ver nenhum código em qualquer idioma em que um comentário é colocado em uma nova linha após o código a que se refere. Nos EUA, pelo menos, o padrão de fato está comentando antes do código ou na mesma linha após o código. Escrever seus comentários após o código relacionado convida a um teste de drogas, uma avaliação psiquiátrica e / ou uma data com um alicate e uma tocha.

A única exceção em que consigo pensar é em um comentário que marca o final de uma seção comentada anteriormente, assim:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin escreveu um ensaio bem considerado sobre comentários que valem a pena ser lidos. Ele não diz se coloca seus comentários antes ou depois do código, mas diz que nunca os coloca na linha, e eu apostaria muito dinheiro que ele não os colocou depois.

Tente comentar apenas onde for realmente necessário; o código deve tentar se auto-documentar sempre que possível.

Dito isto, a veiculação pode depender: Se você usar uma linha separada para o comentário, coloque-a antes do código real. Se você tiver na mesma linha, coloque-o depois.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Mas nunca:

int i = 0;
// this workaround is required to make the compiler happy

Na verdade, não sou um grande fã de comentários. Durante um curso de engenharia de software, fui apresentado à idéia de código de auto-documentação. O código é a única documentação correta 100% garantida de si mesma - os comentários precisam ser atualizados, cuidadosamente construídos e relevantes, caso contrário, são armadilhas que podem ser piores do que nenhum comentário. Não foi até eu começar a trabalhar em uma loja C ++ com um guia de estilo rigoroso e convenções de nomes significativas que eu realmente internalizei esse conceito.

Às vezes, comentários são necessários. Muitas vezes, a nomeação cuidadosa de variáveis, o uso significativo de espaço em branco e o agrupamento e uma organização lógica significativa do próprio código eliminam a necessidade do comentário.

Isso realmente é uma negação da pretensão e validade da sua pergunta, em oposição a uma resposta para a pergunta que você tinha. Eu ainda acho que é relevante e pode ajudá-lo, e não fui um idiota. Caso contrário, os -1's me dominam.

O fato de o comentário aparecer antes do código ajuda o leitor a ter um contexto para o código que está prestes a encontrar. Muito mais humano do que jogar o código para eles e explicar depois que eles já estão confusos.

OK, farei o caso "depois": o código deve sempre ser a documentação principal, enquanto o comentário (que não tem significado semântico) é como uma explicação entre parênteses. Portanto, colocar o comentário abaixo do código que precisa de explicação deixa o código como a principal explicação e apenas usa o comentário para esclarecimento. Por exemplo,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Se você colocar o comentário antes do teste, o leitor tenderá a ler o comentário como principal e poderá não ler o código de perto, sem perceber que foram enganados:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Para emprestar algumas idéias da redação técnica (pelo menos no idioma inglês), coisas como notas e avisos de advertência geralmente são colocadas antes da instrução ou seção à qual a nota ou o aviso de advertência se aplica.

Não vejo por que o código não pode ser considerado uma forma de redação técnica - cada bloco é uma instrução. Como o idioma inglês, a maioria das linguagens de programação é lida da esquerda para a direita, de cima para baixo. Comentários são observações sobre o código - eles podem identificar erros a serem corrigidos ou coisas que um futuro desenvolvedor precisa estar ciente.

Após esse relacionamento, parece mais apropriado colocar o comentário acima do bloco de código ao qual ele se refere.

Um comentário pode precisar ir acima ou abaixo de um trecho de código, dependendo do tipo de comentário que é: se fornece uma explicação ultra-resumida do que o código faz, ele precisa preceder o código; se esclarecer detalhadamente um detalhe técnico sobre como o código funciona, será necessário segui-lo.

Felizmente, um comentário pode ir acima ou abaixo de um trecho de código, e ainda não deixa dúvidas sobre qual trecho de código pertence, fazendo uso adequado de linhas em branco. Obviamente, os programadores que não prestam atenção ao uso de linhas em branco não saberão do que estou falando; se você é um desses, pule esta resposta e siga em frente com sua vida. Mas os programadores que prestam atenção às linhas em branco sabem muito bem que as linhas em branco são usadas para dividir o código em entidades lógicas. Então, se você vir o seguinte:

[blank line]
/* comment */
{ code }
[blank line]

Você sabe que o comentário pertence ao código e indica o que o código faz. Visto que, se você vir o seguinte:

[blank line]
{ code }
/* comment */
[blank line]

Novamente, você sabe muito bem que o comentário pertence a esse código e é um esclarecimento sobre como o código faz o que faz.

Os comentários acima são os melhores.

se você precisar incluir comentários e seu código não for auto-explicativo, prefiro não ser confundido com um bloco de código; veja "ahh, é o que deveria fazer".

O código pode (e deve) ser "auto-documentado", mas se você precisar ler e entender todas as linhas de código para entender como um método funciona. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Quando analisei esse tópico, descobri que a maioria dos sistemas de documentação legíveis por computador (Doc XML, Doxygen, Java doc etc.) espera que o comentário seja apresentado antes do código ao qual se refere - é melhor permanecer compatível com esse padrão.

Também concordo com o segmento SO - Devemos adicionar comentários após blocos de código, e não antes? ..

Eu também prefiro saber de antemão ...

Costumo converter comentários (tanto os meus quanto os escritos por outros) em instruções de log em nível de rastreamento. Isso normalmente facilita muito a compreensão de onde colocá-lo.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Uma vantagem adicional é que, quando as coisas ficam difíceis, eu posso ativar o rastreamento de log e obter um log de execução mais detalhado.