Self Documenting Code ...

I hope you read Jacob Kaplan-Moss's article "What to Write" ... because I'm not going to talk a lot more about that topic. He does an amazing job of explaining what users are looking for when they approach a code base as well as what a waste of time embedded documentation is.

My perspective on documenting code builds on Jacob's observations. As I've mentioned previously in Your Code Is The Other Team Member, code should read like a book. Your eyes should be able to scan the source unencumbered to glean the meaning. Don Knuth says code should be written primarily to communicate its purpose to humans [not to make the compilers happy].

In order to read like a book, code should be Self-Documenting. And by self-documenting I do not mean Doxygen or Javadoc. I mean, does the code clearly express its purpose in and of itself?

When you write code you need to constantly ask yourself "Am I sabotaging the readability of this code?"

How can we sabotage the readability of our code?

Don't document the literal code, but rather, the intention of the code

Who should I believe in this snippet of code?

// Do foo if check is True ...

if ( ! check_thing_has_occurred())

{

foo();

}

You just broke my brain. Now I've got to drill through the logic to find out if the comment or the code is right.

IDE Code Snippet Macros are an invention of the Devil

What value does this comment bring to this method?

/*********************

Detail: Constructor

**********************/

CCPasswordDlg::CCPasswordDlg(CWnd* pParent)

{

...

How about this?

/*********************

Detail: Sets the quality level based on a 1-10 variant

Pram: iQuality - quality setting (1-10)

Date: Sunday, April 06, 2008

By: Joe Developer

Note: Returns VIDEO_CODEC_SUCCESS if successful, VIDEO_CODEC_INCORRECT_PARAMETER otherwise.

**********************/

int CVideoEncoder::SetQuality( int iQuality )

...

So much of this fluff is auto-generated by some keystroke macro from the IDE. It's a complete waste of space. It breaks the flow of the code and creates more places for the reader to second guess themselves. Even worse, it's not even metadata for a doc generator. It's double junk.

Why do we need a date time stamp in the source? Why do we need the developers name? All that stuff is in the RCS. Don't duplicate it. Why do we need the /***...***/? Modern IDE's highlight method names perfectly. Isn't the bounds check more useful in the code? Can't we look at the source to see the return types? Sure, if this is a public-facing API, then perhaps the summary, variable information and return types are valid ... but not for internal code. Again, I would much prefer to see a working unit test or tutorial that explains how this method should be called in the context of a proper use case. That gives me far more benefit than an auto-generated html page will ever provide.

This is just the low-hanging fruit. The C2 wiki entry on Self Documenting Code gives an excellent summary of other things you can do to make your code more readable. Think about all of these points before you start sprinkling doc sugar all over your source.

If you focus on a consistent coding style and follow these rules for making your code base self-documenting you are well on your way to creating a code base that will out live your team or process. There is one more thing that really make it truly timeless ... establish a religion. We'll discuss this next time.