Code Review #7 – Comment the “why” not the “what”

[This post continues the response to Mike.]

Clean “good” code is good but not enough. Code needs comments — but the right kind of comments.

“What” comments are useless and the most quickly out-dated. An example of a what comment is: “add the suffix path to the end”.

However, the post “Thoughts on how to evaluate code” was very specific referring to “why” comments.

Code no matter how “clean” can not self-document. Excellent comments are “why” comments. “Why” comments talk about :

  1. the assumptions / program state the code is expecting. (For example, the user is logged in, premium membership, or admin privileges )
  2. other code affected if this code is changed (For example, setting up a language default for the session, a default that another piece of code is expecting to be set.)
  3. if something is being done in a non-standard way – why it is being done that way (for example, iterating through a loop from high index to low-index rather than the standard low to high)
  4. should the code in question be used as an example pattern of how to do similar operations elsewhere in the code – or should a developer instead use a different pattern elsewhere.
  5. list the assumptions or conditions that require this implementation (with timestamp) so that it is easy to spot code that is present to handle conditions that no longer exist. For example, a comment like this: “12/20/2007 – yahoo’s open id implementation is using the openid 0.8-proposedspec.” Its pretty likely that the the spec has changed as has yahoo’s implementation. This wasn’t a HACK but knowing that reason behind the code is invaluable.
  6. Future work planned.
  7. Alternative solutions that were rejected (and why).
  8. Performance considerations – this code might be special because it executes millions of times a second. So there is good reasons for some “ugliness”.
  9. Update: Why the code was NOT done in a certain way.maybe the usual way to do a certain operation has resulted in a bug (reference the bug number in the comment! )
  10. Update: You, as a developer, are confused by the code. Document your confusion! You may have just discovered a bug.
  11. Update: Document other code looks related for a possible later refactoring.
  12. Update: Document code that should be removed ( Java’s @Deprecated is very useful in this regards because IDEs can mark references to the deprecated code )

The developer, at the moment they are writing the code, must be able to explain why they are writing the code a certain way. It is a red flag to any developer if they cannot explain the why. They should double-check to make sure they understand the requirements. Chances are they don’t and they are doing the wrong thing.

I started requiring developers to clearly document the “why” in their code. I discovered developers that were doing things “wrong” because they were unaware of the correct solution. I discovered that I was not as clear in conveying the requirements as I really thought. Without the developer’s “why” comment, it is easy to get frustrated with developers for the wrong reasons.

Parting thought

Why should the developers that come after the original developer have to spend any time ( and money! ) figuring out the previous work?

You may be the next developer.

This entry was posted in code review, management, technical. Bookmark the permalink.

7 Responses to Code Review #7 – Comment the “why” not the “what”

  1. You have the exact right idea in your parting thought, but comments are not exactly the way it should be gone about. All too often they are a clumsy clutch for a poorly designed interface. Typically a well designed application will have very few comments and the ones it does have will be edge cases which have no other clear method of explanation.

    The understanding of an application’s flow should be well defined and easy to follow by the interfaces presented. Functions and methods should be short, and then even shorter than that. Assuming you are developing in an object oriented language you should strive to follow the principles mentioned here:

    In particular you will notice your classes are smaller and easier to read.

    Assuming you are in a strictly typed language you can make use of this in your interfaces to clear ambiguity between argument lists. You should however strive to have no more than 3 arguments per function, 2 is good, 1 is better and 0 are ideal when possible.

    Each function should deal with 1 level of abstraction and call other functions to deal with further complexity. In this way you can easily follow the function calls and get a very strong understanding of what everything does. With sanely named functions and variable names this method of coding actually completely negates the need for -most- comments.

    Notice, however, I never said that comments should -never ever- be used. I only said you should not strive for them and certainly they are a terrible quality metric. Comments indicate a lack of ability to express yourself in code. Wherever you have written a comment it is because the functionality of that code segment is not otherwise clear. This strongly implies a problem with the code, I hope you agree with that. There are some important places for comments though and you did cover pretty much all the valid cases here, but wherever you make a comment do a double take and see if a few minutes re-factoring can’t clear up your meaning and avoid the need for a comment.

    I also completely understand that there is a strong need to “Just Make It Work” ™ which is where many comments and kludges pop up and I have professional experience with game programming and with web development (I am currently working for Squareflo new media and am the primary developer on our cornerstone CMS project responsible for almost all our new websites and deployed across multiple servers and client sites).

    When releasing for a deadline there isn’t always time to make all code you write immaculate, however any code which is being built on top of should be cleaned up and properly re-factored (if it needs it) first or dependency will stack up and it will become a severe liability later. Programming is a lot like writing in that you rarely get it right in the first draft, in fact re-factoring is a vital step which is often missed by less experienced developers.

    The primary difficulty is when working with a “messy” language like PHP where clean code can be written, but is much more difficult to enforce and variables can be passed containing literally -anything- comments become a necessary evil. I call them evil because in the ideal situation your code should read and express intent clearly. When written properly other developers should not have difficulty reading through your code, complicated bits should be realized as deeper abstractions, wrapped in functions with descriptive names and used appropriately. In this way the function name becomes a very powerful documenting tool.

    All of this aside, however, understanding the gist of a system without having to read code-level is a seperate concern and thus having a clearly written project outline which can be viewed seperate from the code is useful. Also, small but useful hints at the headers of interfaces can be useful. There are certainly places where a well-placed comment will save some trouble in understanding how a set of classes is utilized in a large system. But let me be clear, my original post was primarily to disagree with the use of comments to describe code in detail such that a layperson could understand it. This type of commenting is actually bad, crufty, and prone to error. As I am also in a position where I assist in hiring new programmers I am simply giving my two cents on the subject.

    But you have presented an interesting and well written blog otherwise so I am not trying to pick you apart here. I wouldn’t spend the time commenting like this if I weren’t interested in your opinion or in attempting to present a different way of thinking (even if you simply consider my points seriously and then dismiss them.)

    The primary places I use comments is in providing a visual break between classes, and providing small seed comments that will save time in understanding why I implemented something in a particular way. In less well-written cases I will sometimes comment what a particular parameter’s values can be, but usually you want to avoid having flag parameters in the first place as that indicates a function may be taking on too much.

    I do not absolve myself of any problems or messy code, but certainly if you would like a comprehensive code sample of what I believe is a clean program I have a c++ project I recently did for a code sample in presenting to game development studios for a resume I’m in the process of compiling. E-mail me if you are interested, I am actually looking for thoughts on it anyway.

  2. I should mention as well that for the CMS I wrote I have an accompanying 22 page (when copied to word from the html interface it presents) developer manual. I firmly believe documentation is a must for maintainability, but code-level comments are too dispersed and piecemeal to get a proper sense of the project in a “where do I go to do this” type of situation. This is why when I’m at code-level I prefer to see code, but when I need to understand system-level issues a good and up-to-date readme of some kind is helpful to push you in the right direction.

  3. patrick says:

    Hi Mike,

    Thanks for the comments.

    I feel there is a bit of a disconnect in our debate. Coding style, loose coupling, etc as discussed at we agree on. The number of arguments to a function — I am indifferent to. By the time the number of arguments becomes an issue, usually a refactoring is warranted for other reasons.

    The “Just get it done” attitude has its place but usually the short-term burst of speed is paid for rather quickly when the kludgy code needs to be refactored.

    As to the statement that no comments should be written for the layperson, I respectfully disagree. This is the quickest way I know of being fired.

    I was just talking to a non-technical CEO who hired a consulting firm to build the prototype. His technical friend tried to review the firm’s code, The friend told the CEO, “I can try to figure it out. But it would be faster to fire the firm and I will rewrite it.”

    Guess what happened. “Why” comments might have saved that firm’s contract.

    Part of any developer (or any employee)’s job is managing up. Any employee who is not keeping the managers or clients happy is going to eventually pay the price. Part of the way to manage-up is providing lots of comments. These comments reassure the client that their requirements are correctly understood and that progress is being made even though the program does not work yet.

    Without those comments, the developer will start getting more and more calls questioning when the code will be completed. Once those calls start happening, the client is also looking to replace the developer because the trust is gone.

  4. You keep stating making code readable to the layperson is important but I completely disagree. Making code readable and maintainable to other programmers is the aim. I will describe at the end of this comment why this is. In any case comments are not the way to do this, they are a way, but they are a kludge.

    You keep stating not commenting things is a good way to get fired, honestly if a manager without programming experience is looking through code and becomes upset he does not understand it there is a problem. That problem isn’t that the manager who does not program cannot understand the application on a code level, it is that the manager should not be doing that as it is not supposed to be part of the manager’s job.

    The real aim, we both agree, is maintainability. My suggestion is that comments are a poor way of gauging maintainability however you suggested that they are a good way of doing so. This is the crux of our disagreement. My reasoning is that if you write good code you don’t write as many comments. The reason? A comment is a declaration of your inability to clearly state your intention in code. This is the exact reason someone writes a comment to convey information the syntax of the language and the naming conventions they have chosen cannot convey. My argument is simply that too often they are a crutch used to avoid writing more concise, clear, and maintainable code.

    Laypersons should not be doing code-level inspections of any kind. A layperson can hire a programmer or freelancer to do this type of thing and get cross-references on the code quality, but suggesting they should or can evaluate code is like suggesting I could evaluate the structural integrity of a bridge without an engineering degree. This isn’t a case of evaluating a piece of artwork which can be easily appreciated without understanding the strokes of the brush. We are talking about having an eye for the correctness and elegance of a logical problem which is vastly different.

    Specifically about calls concerning the closeness of completion of code, the client is interested in seeing prototypes and incremental working modules. They are not going to be reading your code and looking at the comments in an effort to ascertain the completeness of the project.

    If you are interested in reading more about my opinion (which I understand isn’t very popular, though it does seem to be that the best code I have read has very few comments) I have brought it up for discussion on some forums I frequent. If not, I understand:

  5. Pingback: Just wondering…. » Blog Archive » When to comment

  6. Dave Doolin says:

    This whole series of articles is resonating very strongly with me. I could go on and on and on… I do have some posts in draft, and a set of private notes I use to keep my own head clear about dealing with subcontractors (“If you don’t like to reply to my email, don’t sign the contract.”)

    But I need to get some work done!

    I’ll check back later. In the meantime, I’m linking to you…

  7. Pingback: Code review #10: No emailed code questions | Just wondering….

Leave a Reply

Your email address will not be published. Required fields are marked *