Self Documenting Code

MattManela — Wed, 10 Oct 2007 03:06:00 GMT

I have come across many developers who believe that comments are not necessary to make code readable. They argue that code should document itself. By this they mean that the code you write should be clear and have good enough naming conventions such that you don't need to add extra comments to make it understandable. They say that if you feel you need to write a comment then you should rewrite the code to be more clear.

I agree that any code you write should be as clear and well named as possible. Comments do NOT make bad code readable. However, I do not agree that clean well written code is sufficient documentation in itself. I am not talking about simple comments like:

/*this calls a function which calculates 
the nth fibinocci number */
int fibNum = calculateFibinocciNumber(5);

or even funnier is: ... And I have done this in the past :)

//the owners first name
private string ownersFirstName;

Those comments are useless since they are just repeating what the code clearly states.

Where you really need descriptive comments are situations such as complex algorithms that the best code in the world still wouldn't make clear how it works. Or when a function is using many different objects. While you could understand what this block does after hours of tracing through all the other functions and classes of the objects it uses, it would be much more convenient to have a simple paragraph give you an overview of what it does and how it uses other those objects.

Another argument against the use of comments I hear is that they don't get updated when the code does. This is a problem but this is the burden of the programmer to always update the comments. Keeping your code clean and your comments in synch with your code is part of a programmers job.

I believe any developer who is thrown in to a large code base will agree with me on this.

So my fellow developers PLEASE both write clean code AND write relevant descriptive comments.

Things I have learnt about Seattle...

MattManela — Wed, 22 Aug 2007 08:20:10 GMT

At the beginning of August I moved out to Seattle from New York and since then I have learned some things about this city:

People in Seattle dislike Starbucks but are inexorably drawn to constantly go there. Everyone complains how Starbucks sold out and how there is better coffee at other local Seattle coffee shops but they all still go to Starbucks religiously.
Traffic in Seattle is worse than all of New York city EXCEPT for Manhattan. Traffic here is pretty bad (520? 405?) and beats in my opinion the four other boroughs of New York in severity but nothing compares to the parking lot that is Manhattan.
Homeless in Seattle get up very early and stay out very late. Anyone who travels in Seattle will notice the flocks of homeless people. I feel bad for them but I must appreciate the long hours they work. I have seen the same person at 6:30am and at 9pm in one day.
The Seattle bus drivers are the nicest people in the world. Maybe I am biased coming from New York where most of the bus drivers would ignore you if you did talk to them but the bus drivers in Seattle are extremely nice. They will help you with anything and seem genuinely concerned that get to where you are going. I had a bus driver ask everyone if they were sure that they didn't want to get off at a certain stop. That shocked me. A bus driving making sure no one forget to see if this was there stop.

That is all for now. I will add more as I learn them.

Matt Manela's Blog : Random Thoughts

Self Documenting Code

Things I have learnt about Seattle...