« Psychology is a science, NOT just Common Sense | Main | Tips on writing C macros »

November 18, 2008

Comments

adamo

I once read that documentation is a set of hypotheses to be tested and not a set of axioms to be trusted. I think that this brings even more light to what you are trying to show.

John Melas

And what if comments are the imperfect translation into a human language of what you failed to understand what the code should do?

Dimitris Staikos

@Melas
I have heard this poor excuse many times before. The funny thing is that the people who tout it not only are bored to write comments, but also DO NOT bother to read other people's comments!

In any case, even if the comments are imperfect, they still provide me more information to work with.

But let's play with words a little here.
If the possibility of someone writing bad comments is excuse/reason for NOT writing comments, then what about the possibility of someone writing bad code?
We still permit most people to write bad code, so let's permit them to write bad comments too.

William Smith

I've recently changed careers to join the ranks of professional programmers. One of the first questions I had at my new company was "Why are there almost no comments within the code?" The Architect's reply was "We want the code to look as clean as possible. And besides, the CODE IS ITS OWN DOCUMENTATION, so you really shouldn't need comments."

As a former project manager I thought this was the most bizarre response to a question I had ever received. Its nice to know that my initial instincts are shared by other reasonable people. :)

The comments to this entry are closed.