> I think comments within code are often a waste of time, at least > in high level languages. The code expresses the ideas logically > and unambiguously, which is much harder to do in a natural > language. If the functions and variables are given sensible > names, their meaning is usually clear enough. (Writing comments > or documentation outside of a program could be useful, however, > for example in giving instructions about how to use a class.)
Whilst it is clear that fatuous comments are a waste of space and time,
I think your position is overly extreme. Self-document code is a good
thing and as you point out most code can be self-document. This means
that there should rarely be a need for comments within a procedure /
function / method. However, particularly arcane bits of code invariably
need commenting in order to facilitate quick comprehension.
Your point about the code expressing things unambiguously is not
actually always true. Yes it is the case that the compilation /
execution system will (except in tha case of non-deterministic code)
have a single execution model. It is however the case that the
programmer / reader of a bit of code can have the wrong undestanding of
that execution model. This is particualrly true for people working with
multiple languages who can inadvertently apply the execution model from
one language onto another.
> Whenever I've had to understand someone else's code, the first
> thing I do is delete all the comments because they are usually
> just clutter. For example, I've seen the following:
The people you have to work with are the problem I think not the
comments per se.
> # Open the data file and print the data:
> open(DATA,$datafile);
> print <DATA>;
> # Now close the file:
> close(DATA);
>
> or
>
> # For each element in the list, do something to the element:
> foreach $element (@list) {
> DoSomething($element);
>
> }
These comments are classic crap and so should be removed. But
extrapolating from dreadful examples like these to all comments in all
programming languages is a bad move I think.
On another note, when I am given a piece of code to work with I
generally reformat it manually into my own layout. This does two
things: it gets the layout of the code into my style and so makes it
easier for me to read; iand t forces me to look at, if not actually
read, all the code which gives me an overview of the whole thing.
Of course in a context where the code is managed by CVS or some other
code management system, I revert back to the original to actually work
on since to reformat would be to put on-significant changes into the
system. Sometimes of course the layout style is so bade that the new
version is committed anyway!
> I wrote comments in a Perl script recently because I wrote it
> for someone who doesn't know Perl but wants to learn. That was
> the first time I've written comments for a good reason. Other
> times it was because some manager decreed it.
> Where I work now no one writes comments, probably because
> the managers are programmers so they know it's a waste of
> time.
Java (via javadoc), C / C++ (via doxygen) and perl vi it's inbuilt
system provide mechanisms for building nice documentation about the APIs
and usage of the componenets provided by the software. I find this sort
of documentation which is embedded in the source code and then extracted
by tools to be very useful indeed. It provides system level
documentation at the appropriate level (if done properly).
Do you also argue that this is a waste of time?
--
Russel.
====================================================================
Dr Russel Winder Chief Technology Officer
OneEighty Software Ltd Tel: +44 20 8680 8712
Cygnet House Fax: +44 20 8680 8453
12-14 Sydenham Road [EMAIL PROTECTED]
Croydon, Surrey CR9 2ET, UK http://www.180sw.com
====================================================================
Under the Regulation of Investigatory Powers (RIP) Act 2000 together
with any and all Regulations in force pursuant to the Act One Eighty
Software Ltd reserves the right to monitor any or all incoming or
outgoing communications as provided for under the Act
signature.asc
Description: This is a digitally signed message part
