Re: The Last Word on Comments (was Re: Hungarian notation)

[Darius Blasbans <darius@phidani.be>]

Clark L. Coleman wrote:
> 
> I have 15 years industrial software engineering experience on a variety
> of projects in a variety of software engineering environments at 4
> companies. The people who claim to be from industry and have posted
> on this subject have been really disappointing. I shudder to think that
> someone is paying them to develop code if they really think you add
> comments after the code is written.

You made a point here. Comments must be part of the code production process.

> Among the amazingly bogus statements made in this discussion was the
> declaration that any comment indicates that your language was not
> expressive enough, and hence you would ideally have no comments. This
> is surely the most ignorant statement ever made about the subject.

Please excuse me for not feeling concerned about the 'ignorant' adjective,
but I kind of disagree with you here. We try to promote an approach where
comments should be formal as far as possible, hence, executable. Assertions
(pre and post-conditions, etc...) are often understood as a quality insurance
feature, while we consider it as a way for the code to express the implicit
knowledge he (or she) has about how things are supposed to happen in
a formal, standardized, and executable way.

On the other hand, if one uses a Tree of components, using a language
with well-designed genericity, is there anything to comment, really,
about having an object:

    Data: Tree(Records);

I truly believe that higher level languages do contribute to fewer
comments. It is true that if you have a unification algorithm coded
in C++, it must be commented. It is also true that if you use
unification in a language where it is a built-in primitive (consider
Prolog, for instance), how much is there to comment ? Unless you are 
of the "i++; /* increment i */" kind of guy.

> If you have not worked on truly large projects that were proven to
> be maintainable by others after you were finished; if you have not
> worked on dozens of software engineers / hundreds of thousands of
> lines of code projects; if you don't understand what "stepwise refinement"
> really means; if you think programming consists of sketching out an
> algorithm on a sheet of paper and then coding; PLEASE do not waste
> net bandwidth replying to this message. Get an education and some real
> experience first.

I guess it would be childish to compare our experience, trying to convince
each other that "I know the real thing". Lots of big projects are developed
in a pretty foolish way. Huge projects are written with huge amounts of
documentation and comments, and still fail to deliver.

Regards,

Darius