[Lazarus] Lazarus Digest, Vol 99, Issue 32

Giuliano Colla giuliano.colla at fastwebnet.it
Sat Apr 9 17:20:37 CEST 2016


Il 09/04/2016 16:41, Juha Manninen ha scritto:
> Comments are overrated.
> If you think of them as "deodorant masking fishy code" then less
> comments is better.

Comments may help to clarify what is obvious to you at the moment of 
writing, but not to anybody else, and maybe even to you some time later.

You are right that usually commenting code is not very useful. Well 
written code is most of the times self documenting, even if *most of the 
times* doesn't mean *always*.
Commenting variables, on the other side, may be crucial for the 
understanding, and not always names are or can be self explanatory. The 
same holds true for procedure parameters, and function results.

I remember reading long time ago the assembler source code of an Intel 
Real-time nanokernel, where I couldn't grasp what a "crflag" variable 
was used for. It appeared to have to do with some kind of data 
protection but it was rather unclear.

Then the same nanokernel was rewritten in PLM which allows for longer 
identifiers, and "crflag" was renamed "CriticalRegionFlag": suddenly 
everything became clear. The purpose and the usage of the flag became 
obvious. If the declaration of crflag had carried a short comment 
"critical region flag", the assembler code would have been much clearer.

Giuliano





More information about the Lazarus mailing list