 |
Defining Programming Standards |
|
|
|
CHAPTER 4 : Commenting
Ideally, programs should not need commenting. The meaning of the code should be obvious from the identifier names used and from the structure and usage of the code. To the programmer, this is often so. His own code is clear, and he understands its meaning with ease. However, the programmer cannot judge the understandability of his code any more than the artist can judge the greatness of his own paintings. He may guess, but familiarity and vanity may cloud his judgement. The ultimate and only true test of the understandability of a given portion of code is the ease with which someone else (chosen at random), who may have no prior knowledge about this part of the code and who may only have a passing understanding of the entire program, can read and understand from that reading what the code is for, what it is doing and why it is doing it the way that it is. If this can be done without comments, then comments are not needed. Most situations, however, will benefit from some degree of commenting.
|
|
|
|
|
||||
