Como comentar seu código como um profissional: práticas recomendadas e bons hábitos
Publicados: 2019-04-03Escrever código é muito parecido com escrever prosa. Cada pessoa faz isso de maneira um pouco diferente e, por causa disso, todos temos uma voz distinta quando nosso código é lido. Temos diferentes convenções de nomenclatura e diferentes lógicas de solução de problemas. Todos nós pensamos que nosso código faz sentido - especialmente se funcionar - mas outra pessoa talvez não. Para combater isso, todos nós precisamos melhorar os comentários do código-fonte. Dessa forma, quem vier ao lado do projeto terá um caminho claro para entender e melhorar / consertar nosso código.
Como comentar o código - O básico
Para começar, vamos ter certeza de que estamos todos na mesma página em relação ao que são os comentários. Neste artigo, discutiremos comentários in-line dentro dos próprios scripts. Coisas como essa em um arquivo CSS, por exemplo, onde o código legível é dividido por comentários que são ignorados pelos processadores.
/** Body Element Styling **/
body {color:red;}
h1 {size:17px;}
/** Sidebar Widget Styling**/
#email-signup-1 {text-transform:uppercase;}
Cada linguagem de programação possui uma maneira diferente de comentar no código-fonte. PHP, HTML, JavaScript e C # têm símbolos ligeiramente diferentes que iniciam e terminam o código. Embora também existam algumas práticas específicas de linguagem, há mais compartilhadas do que não.
Discutiremos alguns dos diferentes tipos de comentários que você encontrará, seus usos e práticas recomendadas (ou talvez apenas bons hábitos para entrar) ao usá-los você mesmo.
Os princípios básicos de comentar seu código são simples:
- Faça-os breves
- Mantenha-os relevantes
- Use-os liberalmente, mas não em excesso
Se você puder manter isso em mente, você estará indo muito bem.
Um momento para discutir os pessimistas
Muito brevemente, vamos tocar no código-fonte comentando contra. Existe um não pequeno subconjunto de desenvolvedores que acreditam que comentar seu código deve ser uma ocasião excepcionalmente rara. Quando você precisa de comentários de código-fonte, é uma indicação de que seu código é fraco de alguma forma. Que suas convenções de nomenclatura, lógica ou qualquer outra coisa não sejam tão transparentes quanto deveriam ser.
E, para ser justo, esse argumento faz certo sentido. No entanto, existem várias circunstâncias que tornam um argumento mais do que suficiente para incluir documentação na forma de comentários, independentemente de quão bem escrito e fatorado seu código seja.
Os principais são que nem sempre você será o único a trabalhar no projeto, e você não pode garantir a experiência da próxima pessoa. Mesmo se você escrever um ótimo código, há uma chance de confusão e ambigüidade.
Documentação do Bloco de Cabeçalho
Se você olhar em alguns arquivos, o código não começa imediatamente porque há um grande cabeçalho no arquivo que descreve sua finalidade, as variáveis, funções, métodos e assim por diante. Eles podem até estar em uma caixa gigante ao redor para chamar sua atenção para ele.
Este não é um bom hábito para se adquirir. Porque é meio inútil. Bem, é realmente inútil, na verdade.
Além disso, observe o exemplo acima: o cabeçalho do comentário é absurdamente longo. Há muito raramente razões para fazer isso. Portanto, não faça isso.
Qualquer coisa que você colocar nesse arquivo deve ser colocado em sua documentação de qualquer maneira. Ter isso em um comentário é redundante. Além disso, o usuário final provavelmente nunca entrará em seu código-fonte, então o comentário seria visto apenas por outros desenvolvedores (ou usuários dedicados do software que já conhecem a documentação).
Além disso, sempre que a documentação for alterada, você deverá alterá-la naquele arquivo. É fácil perder uma etapa e sua base de código pode ser seriamente prejudicada.
Quando os comentários do cabeçalho são úteis
Comentários de cabeçalho são úteis no código-fonte para explicações simples sobre o que esperar desse arquivo. Por exemplo, este é um script que vem com um mecanismo de desenvolvimento de jogo chamado RPG Maker, e o arquivo JS principal que controla cada cena do jogo começa assim:
//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================
//=============================================================================
/**
* The Superclass of all scenes within the game.
*
* @class Scene_Base
* @constructor
* @extends Stage
*/
function Scene_Base() {
this.initialize.apply(this, arguments);
}
Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;
Além disso, observe que o número da versão está listado no topo. Fazem isto. No entanto, não forneça uma lista abrangente de datas em que o arquivo foi alterado e novas versões publicadas. Isso é registrado no Git ou outro software de controle de versão e deve estar disponível para qualquer pessoa que precise dessas informações. O número da versão é suficiente para a maioria das pessoas que veriam este arquivo.
Documentação em linha
O tipo mais comum de comentário de código-fonte é o comentário em linha. Há uma linha tênue entre fazer certo, exagerar ou ser muito parcimonioso com eles. É um equilíbrio que você só precisa aprender com o tempo, mas existem algumas regras práticas muito boas a serem consideradas.
Não faça comentários linha por linha. O comentário in-line é uma coisa. O comentário linha por linha faz com que o código pareça quase ilegível. Veja abaixo:
function sourceCodeComment () { //calls a function
var comment = document.getElementbyID("Code Comment").value; // declares a variable
if (comment != null && comment != '') { //starts an if statement to evaluate if there's a comment
return console.log("Thank you for your comment.") //prints a string to the console
}
Isso é exagero. Se for necessário, faça antes ou depois da função. Mas não em cada linha. É intrusivo e geralmente inútil. Um comentário antes da função (ou elemento) é bom para organização e clareza. Mais do que isso deve ir para a documentação.
Se você acha que é necessário documentar, algo assim será o suficiente.
//checks to see if there's a comment. If so, returns a thank you message.
function sourceCodeComment () {
var comment = document.getElementbyID("Code Comment").value;
if (comment != null && comment != '') {
return console.log("Thank you for your comment.")
}
Os pessimistas mencionarão que mesmo esse tipo de comentário é redundante porque boas convenções de nomenclatura para suas funções, variáveis e métodos tornarão o código legível. Isso é verdade até certo ponto, mas se você pretende manter a ambiguidade no mínimo absoluto, um comentário rápido é o caminho a percorrer.
Não há problema em colocar avisos nos comentários do código-fonte
Às vezes, a solução óbvia para um problema não resolve realmente o problema. Nesses casos, os desenvolvedores que chegam a um projeto posteriormente no desenvolvimento podem olhar para um arquivo e considerar a refatoração para aquela solução óbvia . Fazer isso será uma completa perda de tempo.
Ou talvez algo mais apareça no futuro, e eles tentam chamar uma função que quebra tudo e coloca o projeto de joelhos.
Independentemente disso, se você tem algo que sabe com certeza que não funcionará e que sabe que outras pessoas provavelmente tentarão no futuro, não há problema em avisá-los sobre isso.
// Don't bother trying to use goodCodeComment() here.
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.
function simpleOkayCodeComment() {
//some kind of code goes here
}
Além disso, você percebeu o que fizemos nesse exemplo? Não apenas avisamos os desenvolvedores futuros, mas incluímos um comentário de espaço reservado no meio de uma função. Como os comentários do código-fonte são ignorados, você pode usá-los para manter o texto do espaço reservado no arquivo (como uma espécie de anotação para você mesmo para retornar lá, ou como um exemplo para alguém como uma explicação).
Não seja um idiota
Já vi isso acontecer antes, especialmente em projetos de código aberto que não foram moderados muito bem. Alguém encontrará um trecho de código menos do que estelar e usará um comentário para denegrir o autor.
//This function looks like it was written by a third grader. //It shouldn't work, but it does somehow. I don't want //to fix it because I want you all to see how bad it is.
Ou talvez eles consertem o código, mas incluam o código, simplesmente comentado, para que possam mostrar seu código, enquanto ao mesmo tempo zombam do autor anterior.
//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.
// function theMatrix() {
// var neo = maybeTheOne.data + theOracle.data
// if theOne() !== neo
// return console.log("you got the gift, but it looks like you're waiting for something")
// }
Apenas certifique-se de nunca fazer isso. Mesmo que você ache que está sendo engraçado ou que isso o faz parecer bem, não é e não faz.
O uso real de comentar o código é mantê-lo à mão enquanto tenta outra coisa. Ou para dar um exemplo do que não funcionou antes para que ninguém tente novamente em vão.
Comentários do código-fonte para WordPress
Em geral, o WordPress é executado em quatro idiomas diferentes. HTML, CSS, PHP e JavaScript. Certificar-se de que usar os caracteres corretos para os comentários é fundamental.
Para HTML:
<!-- comments go here and can be single or on multiple lines --></em>
Em CSS:
/* Any number of lines will be a comment until the comment is closed */
Tanto o PHP quanto o JavaScript têm os mesmos métodos para fazer comentários de uma ou várias linhas:
<?php function(); // a single line comment is like this ?>
ou
<?php /* unlike above, you can carriage return and no matter how many lines you use, the comment won't stop until closed */
Conclusão
Se você está nas trincheiras dia após dia, escrevendo código e enviando para o GitHub, sua organização pode ter um guia de estilo para os comentários que deseja que você siga. Se isso não acontecer, ou se você estiver sozinho, manter essas coisas em mente não apenas tornará seu trabalho mais fácil no futuro, mas também ajudará qualquer pessoa que vier atrás de você.
Quais são suas dicas e truques para obter o máximo dos comentários sobre seu código?
Imagem de destaque do artigo por Skillup / shutterstock.com