July 2, 2011

Self Documenting Code

To be fair, some documentation is always a good idea; however, one thing that I've noticed over the years is people who feel it is a requirement. Personally, comments have only been somewhat useful for me after looking back at my code from years ago. Why? Comments take up space. I fully understand how useful comments would be back in the days with heavy assembly programming, but in high-level languages such as Java or C# (no, I don't consider C++ high-level anymore, its more of a mid-high) if the code is written "properly" and written to be easy to understand (typically done by extracting common code) then comments simply waste space.


Usually, when I look up code I see it being documented, which is good, but then I also find extensive commenting where it would have been better to just write self-documenting code. Documentation is great for libraries because you don't usually have direct access to the code. When you do have direct access to code it seems to be a waste. Example, I was looking up an algorithm and the guy had written in a significant amount of comments/documentation. Did it help? No. I spent more time reading comments than code, so simply removing the comments and looking and the code alone (with a few refactorings for names) it took me minutes to figure out the code. I literally cut the content down by more than half because of the comments.


I'm I saying commenting is bad? No, it should just be done in moderation, because it takes almost more time to write it than the code itself, then take into account maintainability. Those two alone are very costly, whenever you need to produce or modify code. If you instead write easy to understand and simple code you won't even need to document. If you choose variable names that are descriptive then you won't have to sit there and refer to documentation on what epsilon means.


Think of this code inside of a class called box:

int static getType(int w, int h) {
    if (w == h)
        return 0;
    if (w > h)
        return 1;
    if (w < h)
        return 2;
}

So what do you think it is supposed to do? Well, lets look at it again with comments:

 /** 
  *  Finds the type of box based on its dimensions
  *  a - first side of the box
  *  b - second side of the box
  *  returns 0 if it is a square, non-zero if it is a rectangle
  *  and 1 if width side is larger than the height side or 2 if
  *  height side is larger than the width side
  */
int static getType(int w, int h) {
    if (w == h)
        return 0;
    if (w > h)
        return 1;
    if (w < h)
        return 2;
}

Now, you probably get what it is trying to do, but how long do you think it took me to do the second code section compared to the first one? How long did it take you to read the second one compared to the first one? And how many things do you think I would have to change if I decided to change the return type to an Enum?  So what would I write?

Well take a look:

BoxType static getBoxType(int width, int height) {
    BoxType type = null;
    if (width == height)
        type = BoxType.Square;
    if (width > height)
        type = BoxType.HorizontalRectangle;
    if (width height)
        type = BoxType.VerticalRectangle;
    return type;
}

So what is horizontal and vertical rectangle? Well, you don't need comments to figure out what the difference is. Look at the conditional statement prior to the assignment. What is BoxType? Well its a type of box, looks to me like it can be either a Square or a Rectangle. As you can see, this code essentially doesn't need to have comments, or documentation unless you cannot look at the source code.

Could I have changed the above code to return an Enum, sure... but wouldn't I then also have to update the documentation? :P

No comments :

Post a Comment