Some examples of how I comment my code - C, C++ or assembler.
Robin Whittle
To the Csound directory
UGENS2.C 38 Kb Wed Jan 31 23:41:58 1996
UGENS2.H 3 Kb Mon Aug 28 16:09:18 1995
UGRW1.C 118 Kb Tue Aug 27 20:11:10 1996
UGRW1.H 15 Kb Sun Jan 07 20:47:00 1996
UGRW2.C 16 Kb Sat Sep 09 16:18:18 1995
UGRW2.H 3 Kb Sat Sep 09 15:18:52 1995
rw970107.txt 8 Kb Wed Jun 03 19:35:40 1998
rw970107.zip 149 Kb Sat Mar 22 21:32:00 1997
tabread.txt 13 Kb Sat Dec 27 17:44:56 1997
Below are some UGRW1.C versions with C++ style // comments and
indentation every 4th column. (I originally wrote it with tabs
at every 8th column.) This layout has most comments to the right,
is so I can see the code (including data declarations) clearly,
without clutter.
One should be able to learn most of what there is to know about
the program by reading the comments alone. They act as a check
against the code.
In the future, if some poor soul - probably me - has to look at
the code in the future and try to figure out:
1 - What the code is doing.
2 - What the original programmer intended it to do.
3 - How well the code performs the role the original programmer
had in mind.
4 - How well the code and its original goals matches a new
purpose.
5 - How dependent the code might be on some other items, such
as the compiler, other modules etc.
then good comments at least make the second problem easy to solve,
which makes everything else easier.
"The Future" means any time more than 10 minutes from the time
the code was written. I am not joking. Write some lines of C
or whatever, then go and write some more lines. 10 minutes later
go back to the first set of lines and I am sure there will be
instances where you can't clearly remember what you were trying
to do, or how you intended to do it.
The typical situation (most programs seem to be written without
adequate comments) involves the poor soul reading the code,
figuring out what it does (much harder without comments),
figuring out what the programmer probably wanted it to do (best
done by a mind-reader with a time machine), and deciding whether
there is any difference.
This nearly as difficult as reverse engineering raw machine code.
Yet comments carry no cost to the compiler or run-time program.
They use 100% recycled electrons and have no carbon footprint.
I generally write the comments, in rough form at least, before I
write the actual code which follows them. This makes it much
easier to write software which works. When writing comments I
frequently have insights into the true nature of the problem and
better ways of solving the problem, when writing the comments.
In some ways, it is like two people in a courtroom, debating each
other, one testing the other. The comments document what exists
before the code runs, what the code is supposed to achieve, and
how it achieves it. Then the code is supposed to follow this.
Frequently, when writing the code, I see that the ideas I
developed in the comments are not right. Frequently, when
refining the comments to explain what I am really doing in the
code, including in low level detail most programmers don't feel
like documenting, I find that I made a mistake with the code, or
in my conception of the work to be done.
Most programmers don't go to this trouble. It is as if they
don't care about layout, or as if they will remember their
intentions and methods for years to come, or as if they really
want to save keystrokes and make the code very terse, without
many sentences etc. I think this is a mistake. I write this
way because for me it is the best way of making software which
actually works. I don't do this for show. I write this way
for code no-one else ever sees.
I assume that people have a screen which displays 40 to 60
lines at once. 25 line screens went out of style in the early
1990s. I think there is a lot to be said for running the
comments and code out to 90 columns or so - as long as it
prints nicely without requiring too small a font.
I think a major part of the problem is that most programmers are
males and males are highly predisposed to *doing* things without
much talking.
I think the people who wind up writing computer programs are
generally appalled at the idea that a man should talk so much!
In hunter-gatherer days, probably the men who were most
reproductively successful were those who simply speared the
woolly mammoth and dragged large slabs of it back to camp,
without any fuss. *So* impressive to the keenly observing
womenfolk who are attracted to the strong silent type . . .
Besides, it is not a good idea to have lengthy conversations
with your colleagues while preparing to spear a wild animal or
attack the neighboring tribe.
In software engineering, however, it is easy and highly
desirable to fully document the functional bits which do the
work. I think this is the fastest and easiest way to create
programs which work.
The box below has a section of the code the way I wrote it,
except it is now with 4 column indentation and // comments.
These are the files:
ugrw1-t4-slash-comments.c.txt
ugrw1-t4-slash-comments.c.html
ugrw1-t4-slash-comments.h.txt
ugrw1-t4-slash-comments.h.html
When it was integrated into Csound, UGRW1.C as reformatted by
the Csound maintainer: to mash my carefully separated comments
into the midst of the code. I think it is much harder to read.
The indentation has been changed to 2 columns, which I think
is OK, but I prefer 4.
ugrw1-comments-reformed.c.txt
ugrw1-comments-reformed.c.html
The code was highlighed with Gnu Source-highlight http://www.gnu.org/software/src-highlite/
// Wrap and guard point mode.
//
// In guard point mode only, add 0.5
// to the index.
else
{
if (liwgm == 2)
ndx += 0.5;
indx = (long) floor(ndx);
// Both wrap and guard point mode.
//
// AND with an integer like 0000 0111
// to wrap the index within the
// range of the table.
indx &= mask;
// Calculate the address of where we
// want to write to, from indx and the
// starting address of the table.
}
pwrite = ptab + indx;
// Write the input value to the table.
// Auto increment pointer to input
// array.
*pwrite = *psig++;
// If this is guard point mode and we
// have just written to location 0,
// then also write to the guard point.
if ( (liwgm == 2) & indx == 0 )
{
// Note that since pwrite is a pointer
// to a float, adding length to it
// adds (4 * length) to its value since
// the length of a float is 4 bytes.
pwrite += length;
// Decrement psig to make it point
// to the same input value.
// Write to guard point.
psig--;
*pwrite = *psig++;
}
}
while(--nsmps);
} |