Esta pergunta está me obcecando nos últimos 2 meses.
Há algum tempo, um amigo que é um grande programador me deu alguns exemplos de códigos e, pela primeira vez, notei um estilo único de organização de comentários. Ele se esforçou para criar comentários de uma maneira que me deixasse mais confortável com o próprio código. Por exemplo:
///////////////////////////////////////////// // //
// This code prints a basic "Hello world" //
// message to the console screen. You can //
// change the text in the brackets. //
// //
/////////////////////////////////////////////
#include <iostream>
int main() {
cout << "Hello world";
}
quando ele poderia simplesmente escrever
/* This code prints a basic "Hello world" message to the console, change text in brackets */
#include <iostream>
int main() {
cout << "Hello world";
}
Este tipo de exemplo apenas em uma escala maior. Acho isso um pouco improdutivo em situações profissionais, mas em uma situação de aprendizado, parece ideal.
A questão aqui é, se o estilo do comentário afeta o modo como o leitor entende o código. Na minha opinião pessoal, a opção 1 é mais bonita aos olhos e mais fácil de seguir do que a 2. A maneira como você comenta o código afeta a capacidade de compreender seu código ou é apenas desperdício de tempo e espaço?
Respostas:
sim
O layout de um programa da perspectiva de espaço em branco e comentários terá um grande impacto sobre a capacidade de um desenvolvedor ler seu código.
Prettier to the eye and more easy to followsão subjetivos e não serão os mesmos para todos os programadores.Dito isto, alguns desenvolvedores preferem ver mais código na tela ao mesmo tempo, enquanto outros preferem ter mais espaço em branco / comentários.
No final do dia, você ficará mais confortável lendo o código que está acostumado a ler.
Tio Bob Martin, autor do Clean Code, argumenta que os comentários são freqüentemente usados para desculpar códigos incorretos e devem ser evitados sempre que possível. Em vez disso, seu próprio código deve ser legível e organizado bem o suficiente para permitir que outro desenvolvedor o pegue e comece a trabalhar facilmente.
fonte
Acredito que a formatação do código pode fazer uma enorme diferença na legibilidade, mas a maioria dos códigos bem formatados (ou mesmo apenas recuados de forma consistente) me dá uma sensação calorosa e confusa de que o escritor realmente tomou um pouco de cuidado, em vez de apenas cortar colando quaisquer trechos que ele ou ela tenha em mãos.
Não tenho tanta certeza sobre comentários. Código que eu escrevo, acredito firmemente que o comentário ajuda. Por outro lado, se eu quiser entender o código "corporativo" que encontro no trabalho, costumo excluir todos os comentários, reformatar o código para ter um recuo consistente e imprimi-lo no papel para ler em detalhes, marcando os blocos básicos com lápis etc.
Essa contradição (eu: bons comentários; todo mundo: comentários enganosos) me faz pensar que os comentários são superestimados. Até o meu.
fonte
Sim, comentar estilo afeta a legibilidade (como não pode?), Mas eu diria que o exemplo que você deu é um estilo muito ruim. Formatação excessiva é apenas isso: excessiva.
Escrever bons comentários é uma habilidade a ser praticada e refinada, assim como escrever código.
fonte
IMHO, o primeiro é adequado para comentar o que uma classe faz ou no início de um arquivo de origem; o segundo é adequado para descrever o que o seguinte bloco de código faz. para métodos, eu usaria
Além de outras ótimas respostas, acho que a consistência no estilo dos comentários é outro ponto. Se você usar diferentes tipos de estilos de comentários para o mesmo tipo de tarefas que prejudicariam bastante a legibilidade do seu código.
fonte
O exemplo que você dá é um pouco extremo, mas sim, os comentários têm uma função muito importante.
O escritor do código tem um modelo mental do que ele precisa fazer. Os comentários servem para
Dessa forma, se os requisitos forem alterados, é mais provável que as alterações correspondentes no código possam ser feitas corretamente, seja pelo autor original ou por qualquer pessoa que aparecer posteriormente.
Também é bom tentar escrever o código de tal maneira que ele se explique, mas que raramente seja 100% bem-sucedido, portanto os comentários são necessários.
fonte
Uma resposta rápida para a pergunta é "Sim". Comentários e estilo de comentário afetam claramente a legibilidade e a compreensão do código. Essa é a ideia geral, mas a qualidade das descrições dos comentários e seu design é puramente subjetiva.
Você já tentou ler o código e os comentários de outra pessoa? A maioria dos programadores escreve código e comentários com base em seu próprio estilo e nível de conhecimento. Ler os comentários e o código é como tentar entrar em sua mente e seguir suas práticas.
Uma maneira de evitar esse problema é usar um “guia de princípio / estilo” básico que descreva brevemente as diretrizes básicas para estrutura, finalidade e comentários do código. Este guia deve ser seguido consistentemente pelas pessoas que escrevem o código e todos os demais que possam ler o código e possivelmente estendê-lo.
fonte
Estilisticamente, eu usaria duas formas de comentário (para C ++ / Java)
ou
um IDE com realce de sintaxe é suficiente para chamar sua atenção para o comentário; você não precisa gostar da formatação.
fonte
Sim, o estilo de comentar certamente afeta a legibilidade. Qualquer estilo de comentário que permita identificar comentários rapidamente, para que eu possa evitar lê-los, ajuda tremendamente quando o que realmente estou tentando fazer é ler o código .
Ainda melhor é um estilo de comentário de código que me permite usar o IDE para minimizar completamente os comentários, de modo que não precise gastar energia para ler em torno deles.
fonte