Why is a good start. But documenting the who, how, where, and when are important, too: * Who is meant to use this code? * How is this code supposed to be call

Why is a good start. But documenting the who, how, where, and when are important, too: * Who is meant to use this code? * How is this code supposed to be called? * How is it organized? * How does it do its job? * Where are the dependencies? * When is it appropriate to call it? And finally, the What is also extremely important at a macro level: * What does this block of code do? * What are the gotchas? * What special requirements are necessary? Obviously, commenting isn't typically as useful at the granularity of a single line of code. But the bigger the block of code these questions document, the more important they are. By the time you get to a class or file level, they're essential. I think that every programmer should take a course in journalism, so that they understand the critical importance of the 5w's + h. But I'd settle for programmers who actually take the time to write comments. An extra 10% of your time saves your team exponential time in the future, because it cuts down on the communication overhead. There's simply no valid excuse for not writing comments -- only laziness.