syque.com

The Psychology of Quality and More

| Menu | Books | Share | Search | Settings |

C Style: Standards and Guidelines (contents)

CHAPTER 4 : Commenting

PART 2 : COMMENTING AND NAMING

CHAPTER 4 : Commenting
4.1 Commenting fundamentals
4.2 Comment types
4.3 Header comments
4.4 File Header comment
4.5 Function header comments
4.6 Block comments
4.7 Trailing comments
4.8 Commenting data
4.9 The preprocessor and comments
4.10 Summary 

<--Prev page | Next page -->

 

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.

 

<--Prev page | Next page -->

 

Site Menu

| Home | Top | Settings |

Quality: | Quality Toolbook | Tools of the Trade | Improvement Encyclopedia | Quality Articles | Being Creative | Being Persuasive |

And: | C Style (Book) | Stories | Articles | Bookstore | My Photos | About | Contact |

Settings: | Computer layout | Mobile layout | Small font | Medium font | Large font | Translate |

 

You can buy books here

More Kindle books:

And the big
paperback book


Look inside

 

Please help and share:

 

| Home | Top | Menu |

© Changing Works 2002-
Massive Content -- Maximum Speed