Code commenting? Try Business Commenting.

Jeff has a good post here about code comments and that they shouldn't be used as crutches:

Coding Horror: Coding Without Comments

I agree with the article, but one thing I rarely hear mentioned is that it's often more interesting to comment the business justification than it is to comment the code. Jeff goes some way towards suggesting this when he says to comment the "why", but for many people that translates to "Why did I write the code this way?".

I often find that code I'm maintaining is missing comments regarding the business logic. Rather than "Why is the code designed like this?", something like "Why is the business process designed like this?"

This becomes most useful when you look at unfamiliar code (your own, probably) and decide that the easily-digestible code is nevertheless doing something you are sure is silly, and you change it. Big mistake.

Example of a code architecture comment:

    1: // We cache these values because they only change once per

    2: // week or so.

Or:

    1: // We lazy-load these properties because they're rarely used

    2: // and they chew up a decent amount of RAM.

Example of a business architecture comment:

    1: // We copy the lab owner on this mail because even though

    2: // they don't own this resource, they wanted to be aware

    3: // of changes. See bug 54321 for request and history.

Or:

    1: // This used to delete items older than 30 days, but

    2: // bug #65432 requested that an exception be made for

    3: // items that are of type X.

All are useful, but I find the second type are rarely used. They become more valuable as the code ages.

Avi

Comments

• Anonymous
  July 24, 2008
  PingBack from http://www.alvinashcraft.com/2008/07/25/dew-drop-july-25-2008/
• Anonymous
  July 25, 2008
  Excellent, excellent, excellent!(and no, this is not a SPAM comment ;-)(wouldn't a SPAM comment say it's not a SPAM comment?)(and no, this is really no SPAM comment, the post is excellent and I often wish there was a business comment in the code I read to know why a developer wrote code in such a - sometimes complicated - way, so I don't violate a business requirement when refactoring or "fixing" the code.)Peace-stephan
• Anonymous
  July 25, 2008
  I do not have much experience in writing system level code, but I agree to Jeff's post that determining whats happening from it is really difficult.On the other hand, when you are writing business applications, you would really want your code and test to do the talking. The code should be written as close to the Domain and the Test should act as a good specification such that you should never require any comments.Fine examples of this kind of effort are Domain Driven Design, Behavior Driven Development. An example API being jmock
• Anonymous
  July 25, 2008
  I am going to start write comments like that. Thanks
• Anonymous
  July 25, 2008
  I use a bit of both, but never really thought much about it. Now that it's spelled out this way, it makes a lot of sense.Big up, mate!
• Anonymous
  July 25, 2008
  Folks -- business logic is described in specifications. Do you have documented specifications for software you write?
• Anonymous
  July 25, 2008
  nice list, thanks for sharing.
• Anonymous
  July 26, 2008
  It looks like you're putting data into the code. I separate data from processing logics.There are only so many working at companies where this "business commenting" would even make sense. I work with a completely general platform that doesn't have special-cases at all.Besides, your "business comments" are as much "code architecture comments" because they do comment the code and how it works, implicitly. They, too, will need to be updated when the code changes.I call shenanigans and whine over nothing.
• Anonymous
  July 27, 2008
  @Anand: "On the other hand, when you are writing business applications, you would really want your code and test to do the talking."If you're looking at the code, you don't want to see something like "includeLabOwnerEmailPerBug1234()". Use a comment: without it it won't be clear why you're doing something.Tests examine what's happening. Not why. And yes, you could name your test "ensureLabOwnerEmailedAsPerBug1234()", and if your test methodology includes source-level references from the code under tests to the tests perhaps that's enough. I don't think it is, but at that point it's largely a matter of preference.
• Anonymous
  July 27, 2008
  Sometimes it is important to say why a bit of code was written this way. I can't tell from your ambiguous wording whether you were being dismissive of this practice or not, but certainly some readers will read it that way.If my code is:if ( $pid = fork ) {...I do want a comment there saying that I DID mean to say '=' and not '==' so that maintenance programmers, including myself a year later, get a hint that the code as written is not buggy (because, without a comment, it does look like a bug to people who don't know what is going on).Your suggestion of commenting business processes is a good one. But your sloppy writing risks leading people to think you are advocating throwing out the baby with the bath water.
• Anonymous
  July 27, 2008
  @Mark: I'm not sure what baby I'm throwing out with which bathwater. As I said, I think both types of comments are valuable.@Brad: Specifications are great, but my experience has shown that they're generally not available at all or not up to date with the code. I wish it wasn't that way, but when it is, I rather have comments like that to protect the code from what seem like innocent changes.At the end, this isn't a right/wrong thing. It works for me in my environment; it may not work for you in yours...
• Anonymous
  July 28, 2008
  <a href="http://www.reddit.com/r/programming/comments/6tqre/no_your_code_is_not_so_great_that_it_doesnt_need/c04uc6y">This reddit comment</a> says it all.
• Anonymous
  July 28, 2008
  .. and the replies in that thread make a lot of sense too!
• Anonymous
  July 30, 2008
  The comment has been removed
• Anonymous
  August 05, 2008
  The comment has been removed