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 10000 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