Saturday, March 12, 2005

Comments

"Real Programmers don't comment their code. If it was hard to write, it should be hard to understand."
(Vleck 1982)

"Document code? Why do you think they call it code?"
(Anonymous)

"Real Programmers don't need comments — the code is obvious."
(Anonymous)

"If a program is useful, it must be changed. If a program is useless, it must be documented."
(Anonymous)

Introduction

Comments are essential and is addressed to the human reader. Comments are also ignored by the compiler (Barron 1977).

Discussion

Comment brackets /* ... */ comes from PL/I, and allows comments to be used where they are meaningful (Barron 1977).

if (n <= 2) /* n == 0, 1, 2 returns 1 for Fibonacci numbers */ return 1; 
/**
 * This is a documentation comment
 */

Documentation intended for the javadoc tool.

References