Nathan CrauseMusings of a Software Developer

It amazes me that in this day and age the question of whether to comment your code is still being raised. This issue is such a no-brainer, I fail to see how so many developers can miss the importance of well commented code.

I've heard all the arguments, ranging from "it takes too much time" to "your code should be self-explanatory". All of these fail in several regards:

1. assumes knowledge - if you're new to a language or a framework, trying to fathom what a product is doing can be extremely frustrating. Not taking into account your project's longevity is extremely short-sighted
2. process complexity - if any given process touches several layers of libraries or code, then expecting a programmer to step through all the levels is stupid. This becomes extremely time consuming. Ruby on Rails is a prime example of this - virtually nothing is commented, so you are forced to wade through the framework's source code. This is not conducive to productivity.
3. variable functionality - a lot of dynamic languages use array or tables passed into methods/function to control their behaviour. If the different behaviour isn't clearly commented, how can you expect someone to use it later on?

None of the arguments against code commenting address these. I know it's not good to point fingers, but this is the biggest issue I have with Rubyists.

As for me - I comment prolifically. The result is that I can come back 2-3 years later and still be able to understand what my code does without having to wade through it all, line by bloody line.

I'd like to address this Slashdot article directly:

1. Big deal. Taking a few extra seconds to update a line or two of code is worth it in the long run. Evidently the writer of this article hasn't worked on projects that have spanned several years and several developers.
2. Comments can make code more readable - especially if you're new to a language/framework. Let's use an example: to me this line meant nothing:
   

   z=x||[]<<'Something'
   

   A simple comment saying "use x (or create new empty array) and append 'Something'" would have saved me a lot of time.
3. Define the term "something that needs no documentation". Someone who is very familiar with a library may not think a piece of code needs commenting, but the next developer to come across it might have no idea what it's supposed to be doing. The idea of "comment everything" is simply a safety net. Obviously you don't need to comment what this does:
   

   if (x == 0) {}
   

   However, it may be nice when performing a class declaration to explain why you even created the class.
4. I don't even know what the point here is supposed to be. This point seems to rather support the use of comments.