Se você é um programador, existem muitas práticas que você pode odiar.
Valores codificados permanentemente. Lógica dupla. Hierarquias de herança complexas. Mas os comentários deveriam estar nesta lista?
Há muito tempo, nos dias da programação pré-histórica, escrever comentários era considerado uma parte obrigatória da escrita de código. Quando você escreveu o código, ele foi preenchido com comentários curtos e precisos. Então, o código limpo e a programação ágil começaram a dominar o mundo. Os puristas gritaram sobre os perigos dos comentários que preenchiam códigos não estruturados e vulneráveis. De repente, os comentários se tornaram um erro, um antipadrão, uma coleção de mentiras descaradas.
Muitos desenvolvedores se sentiram encurralados.
Mas a escolha é tão óbvia? Ou ainda há como escrever comentários e ao mesmo tempo respeitar-se levantando de manhã? Para descobrir a resposta, vamos ver como um código terrível é comentado e como até mesmo um comentário ruim pode salvar vidas.
Comentários preguiçosos
, , .
, , :
double delta = h*h-r1*r1;
double r2 = Math.Sqrt(delta);
, , . , , , :
// Calculate side length using the Pythagorean Theorem
// and put the value into variable "r2"
double delta = h*h-r1*r1;
double r2 = Math.Sqrt(delta);
- . .
. , :
double lengthSideB = Math.Sqrt(
Math.Pow(hypotenuse,2) - Math.Pow(lengthSideA,2);
)
:
double sideA = Pythagoras.GetLengthOfSide(hyptenuse, sideB);
? ! - , , . , . , . - - .
. , , , . , - - . , , . , . , . :
/**
* Constructor.
*
* @param name (required) brand name of the product. Must have
* content. Length must be in range 1..50.
* @param price (optional) purchase price of the product.
* @param units (required) number of units currently in stock.
* Can not be less than 0.
*/
public Product(string name, decimal price, integer units)
{
...
}
, , . - , . . , , .
. , . . . . , , - . API. , , . . - , . , API , , , . . , - . , . .
« - » - , .
. , - :
// to match ITG1's late arrows. -K
GlobalOffsetSeconds=-0.006
, - , . - , , , , . , , , . . , , , . , - , , , , ? - , , , , , .
, , , , . , , , . , . - , - .
“I spent some time this weekend looking at very well-named, very clean, uncommented code implementing a research algorithm. I’m high-level familiar with it, the guy sitting next to me was the inventor, and the code was written a few years ago by someone else. We could barely follow it.” — Paul Nathan
, , . , , , . . , . , , . .
, . . :
( )
( )
( IDE)
A questão principal é simples. Vale a pena pagar pelos comentários? As opiniões diferem, mas se você usar os comentários de forma ponderada e inteligente - se usá-los para reduzir a carga cognitiva de seu código, em vez de neutralizar práticas ruins - eles podem agregar valor até mesmo ao código mais limpo.