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

[clc5q@mamba.cs.Virginia.EDU (Clark L. Coleman)]

In article <4oegks$ntn@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes:
>andyc@procom.com (Andy Ho-Fan Chan) writes:
>
>
>>Well, comment is important, but in academic, most of the time no
>>one wants to do that.
>
>The smart ones do.
>The smart ones know that you should always write the comments FIRST,
>explaining your major data structures and how they work,
>explaining the key ideas behind algorithms,
>and you only start writing code after the comments look right.

Finally, someone gets the point in this stupid discussion. Bravo
to the professor from RMIT. Everyone else in the discussion is
apparently so ignorant of how to design real-world software that
their arguments are pathetic, ESPECIALLY those who claim to be
working in industry and who are taking potshots at the "ivory
tower" requirements for comments.

Has anyone here heard of stepwise refinement? When you design and
implement a system of hundreds of modules and hundreds of thousands
of lines of code, you do not write a design description document and
then start coding. You write a system requirements specification, then
a system design (outlining decomposition into subsystems and the
interactions between subsystems,)  then subsystem design documents
(breaking down each subsystem into modules (and classes, for OOP)),
then module design documents for each module. The module design document
has pseudo-code, among other things. A good software engineering
environment will have a tool that extracts the pseudo-code from a file
and makes the module design document out of it. Then, the code is added
to the same file, interspersed with the pseudo-code comments, and the
code is formally reviewed (as were each of the above documents.)

99% of the postings in this thread have assumed that the code exists,
so how many comments should I add to it later?

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.

Whether you do object-oriented design (as I am currently doing in industry),
or functional or logic or imperative programming, you are going to use
stepwise refinement to move from requirements down to code. As I indicated
above, the number of conceptual levels is 4 or 5 for a big project. The level
that immediately precedes the coding will require pseudo-code, which should
remain imbedded in the final code, not thrown away.

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.

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.

The real problem in academia in this regard is the continual assignment
of projects that will only take 1 to 3 pages of final source code.  The
number of levels of abstraction required in the design process is so few
compared to industrial practice that students will incorrectly think that
you spend little time designing before coding, which will not be true in
general.

-- 
--------------------------------------------------------------------------
"I have prevented my kids from watching MTV at home. It's not safe for kids."
---- Tom Freston, MTV president, 4/14/95 Buffalo News.
 |||  clc5q@virginia.edu (Clark L. Coleman)