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

34

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.

msh210
fonte
3
Considera o que acontece quando você o coloca depois. Programador leu o código. Diga a si mesmo WTF isso está fazendo ??? Veja o comentário. Leia o código novamente. Em algum momento, entenda ou desista. Portanto, seja legal e evite as partes 1 e 2 colocando-as em cima.
deadalnix
@deadalnix, obrigado, que também parece ser a essência da resposta de Dipan Mehta . (Graças também a todos os respondentes, até agora, e uma para cada.)
msh210

Respostas:

22

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.

traço
fonte
1
Marca de seleção, pois esta é a única resposta (até agora) que responde claramente à pergunta, que buscava não preferência pessoal, mas procedimento operacional padrão, na medida em que cita o MSDN.
msh210
1
@ msh210: Então você prefere uma preferência da Microsoft às preferências pessoais de outros bons programadores? Mas você sabe como a Microsoft errou a notação húngara como padrão? Sim? Você? Confie apenas no bom senso, nem sempre corra com a horda ou siga o maior touro.
Falcon
2
@Falcon, nunca ouvi falar da notação húngara e suspeito que a preferência do MSDN foi pelo menos o resultado de várias contribuições de funcionários da MS; as respostas aqui, por outro lado, são de autoria individual.
Msh210
43

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.

Ryathal
fonte
9

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.

Joshua Smith
fonte
7

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.

Dipan Mehta
fonte
6

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.

Caleb
fonte
4

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

Lucero
fonte
Releia a pergunta: especifica que está perguntando sobre um comentário em uma linha separada.
Msh210
2
@ msh210 Esta é uma resposta perfeita. "escrever comentários antes". É ainda mais detalhado e fornece um motivo possível para você pensar que eles estão atrás de "Exceto quando são curtos e estão no fim da linha".
Rd
3

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.

Brian Stinar
fonte
10
O código de auto-documentação pode responder "o quê" e "como", mas não importa o quão bem escrito, o código por si só raramente pode responder à pergunta "Por quê?". Se houver um documento abrangente de requisitos, às vezes você pode encontrar a resposta lá. Caso contrário, os comentários geralmente são tudo o que você precisa para explicar por que o código precisa fazer o que faz.
precisa
1
Eu não concordo Como o @EdStaub diz, comentar responde a uma pergunta diferente, em um nível diferente. O código também não é necessariamente de código aberto. E mesmo quando é, não quero ler um código-fonte da estrutura para saber como usá-lo.
rds
4
Obviamente, você nunca lidou com hardware (ou com interface com software mal escrito). Recentemente, terminei de escrever uma aula especializada para conversar com um controlador de motor bastante obscuro (e irritadiço ). Ele tem todos os tipos de requisitos estranhos para a interface. Exceto por ter literalmente uma função por linha, não há como tornar o código compreensível sem comentar.
Fake Name
3
@Brian, as perguntas "Por que" geralmente são muito refinadas - por exemplo, contornar erros em uma API e / ou explicar que algo que parece errado está realmente correto. Esses são apenas alguns exemplos. Eu não faria comentários ser um documento abrangente de requisitos. Mas também não tentaria explicar a justificativa para cada pequeno detalhe de implementação em uma especificação de requisitos (ou mesmo uma especificação de design, nesse caso).
precisa
1
@codesparkle - Concordo que os comentários usados ​​como desculpa para evitar a refatoração geralmente são ruins. No entanto, isso não significa que todos os comentários sejam ruins, apenas que os comentários abusados ​​dessa maneira são. O fato é que existem várias situações em que os comentários são realmente a melhor opção para esclarecer os requisitos de codificação ímpares.
Fake Name
2

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.

Dan Ray
fonte
2

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){ ... }  
Larry OBrien
fonte
5
Os dois blocos de código têm comentários antes do código que estão comentando.
msh210
seus próprios comentários negados os seus "após caso" hehe :) abraços e +1 para torná-lo um exemplo temático do Natal
Ahmed Masud
1
@ msh210 Eu vejo meus comentários no primeiro exemplo como comentando no teste if (christmas), não como "sobre" as seguintes funções (ou seja, eles estão dizendo "o que significa que estamos aqui?") Eles precedem um bloco de código, mas nunca vi código que tivesse ... code (); código(); / * Comentário explicando anterior bloco * /} e não demorou a questão dessa maneira
Larry OBrien
1

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.

Thomas Owens
fonte
1

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.

Mike Nakis
fonte
Como sempre digo: seu voto negativo sem explicação não me ajuda a me tornar uma pessoa melhor. Amo você também!
Mike Nakis
1

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 ...

Niranjan Singh
fonte
1

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.

mosquito
fonte