Self-Documenting Code Chapter 32

Kinds of Comments  Repeat of code  Explanation of code  Marker in code  Summary of code  Description of code’s intent  Information that can not possibly be expressed by the code itself

Repeat of Code  Tells what the code does in words  Basically useless

Explanation of Code  If code is so complicated or confusing  it needs explanation then it probably needs rewriting

Marker in Code  Typical example:  // TODO: make changes here

Summary of Code  Simple summary of code into one or two sentences  valuable

Description of Code’s Intent  A comment at the level of intent explains the purpose of a section of code.  Intent comments operate more at the level of the problem than at the level of the solution.  For example,  get current employee information is an intent comment, whereas  update employeeRecord object is a summary comment in terms of the solution.  Most useful

Information that can not…  Copyright notices  Confidentiality  Etc  Not what we’re talking about here

Balance  Certainly need a useful amount of commenting  Need to avoid too many comments  If it takes too much time to wade through comments then there’s too much  If there’s as much or more comments than code then there’s too much  Rule of thumb: 1 line of comment for 10 lines of code

Avoid /* */ /* here’s a difficult style of */ /* comment block to maintain */ /* */ /********************************* * class * * hard to maintain * **********************************/

Prefer // // this style is easier because you don’t // have to align the right hand column // you can just copy and paste the dashes // to start and end the block // /*********************************************** keep in mind that your code might not be viewed with a color-coding system ************************************************/

“It Takes Too Much Time”  It takes more time later and is harder to debug  Commenting after the fact is more difficult

Commenting Techniques  Endline comments  Tend to be cryptic  Hard to maintain  OK for data declarations  OK to denote bug fixes  OK for marking ends of blocks  Commenting individual lines  Complicated line of code  Bug repair

Commenting Techniques  Commenting paragraphs of code  Example from “recover.c” // get next cluster fat_index=0; if (cluster >= (FAT_ENTRIES/2)) { cluster = cluster-(FAT_ENTRIES/2); fat_index++; } cluster = *(F_tbl[fat_index]+cluster);

Paragraphs  Write comments at the level of the code’s intent  Focus on the code itself so that comments enhance good code  Focus paragraph comments on why rather than how

Code’s intent  Better comments  // find '$' in inputString  it indicates that the goal of the loop is to find a $.  it still doesn't give you much insight into why the loop would need to find a $  into the deeper intent of the loop.  Even better  // find the command-word terminator ($)

Coment the Why, not the How

Justify “good style” violations  Explain yourself when violating good style to prevent someone from rewriting code in a better style that could break your code.

Don’t comment tricky code, rewrite it  Except if you’re maintaining code and don’t have the latitude to change it.

Other Comments  Flags to bit level  // 0x80 – NW neighbor  // 0x40 – N neighbor  // 0x20 – NE neighbor  Allowable numeric ranges  // this index should never exceed because…  Global data  I prefer a naming convention to solve this:  Example: gMeaningfullyNamedVariable  Coded meanings (could use other methods to accomplish this)  Enumerated types  // 0 – generic land texture  // 1 – herbaceous rangeland texture  Units of numeric data (again, could use other methods)  Meters  Fahrenheit degrees  Etc

Rules of Thumb  Keep comments close to the code they describe  Document parameters where they’re declared  Use Javadoc  Differentiate between input and output  Again, I prefer naming

Routines  Say what the routine WON’T do, mention legal input values  Document global effects  Document source of algorithms  Avoid enormous comment blocks  I like some comments before every routine for visual delineation at the very least