21 Nov
2011
21 Nov
'11
4 p.m.
It was thus said that the Great Chuck Guzis once stated:
On 21 Nov 2011 at 11:06, Brian Wheeler wrote:
I don't add that many comments to my own code. But when I do, it tends to
be stuff like:
/*------------------------------------------------------------------------
; Per http://www.cons.org/cracauer/sigint.html, the only proper way to
; exit a program that has received a SIGINT (or SIGQUIT) is to actually
; use the default action of SIGINT (or SIGQUIT) so that the calling
; program can detect that the child process (in this case, us) actually
; received a signal. So that's why we set the default handler for SIGINT
; and kill ourselves, since the only way we get here is via SIGINT (or
; possibly SIGQUIT if/when I add logic for that).
;------------------------------------------------------------------------*/
set_signal_handler(SIGINT,SIG_DFL);
kill(getpid(),SIGINT);
return EXIT_SUCCESS; /* keep this around to silence the compilers */
}
or
/*------------------------------------------------------------------------
; check for origin field. We only look for IPv4/IPv6 literal addresses as
; that's the only reliable way to actually transmit such information (and
; parse it as intended per RFC3164). Thus, this code will fail if a
; hostname is sent, but it would also fail if the program name with an
; embedded space but no host is sent.
;
; I suppose I could check to see if the first white-space delimited field
; *only* contains alphanumberics, but then it could fail on a message that
; is sent that contains neither a host nor a program (which is possible).
;
; Pick your poison ... this works for me
;-------------------------------------------------------------------------*/
The other trick (I think) is picking good names that reflect what the
function/subroutine is doing. I hope that a function named "GlobalsInit()"
does indicate what it's doing.
-spc (Another question about literate programming---what can I assume the
intended audience to be? A fellow programmer at the same level as
I? An intern? A C*O that's never programmed before?)
No arguments there. I used to manage some
programmers and I'd find
lots of lines like:
a++; // add one to a
Totally pointless.
Heh. I vividly recall a fellow who proudly pointed out to me that
every line of his code had a comment. Unfortunately, most were like:
BX5 X1*X3 LOGICAL AND X1, X3 TO X5
Reading thousands of lines of drivel like this is insulting and
indicates a lack of appropriate focus.
On the other hand, a tight loop, with instruction timings written out
as comments is quite informative.
One more observation. I've read a lot of other people's code in my
lifetime and one thing that stands out in sharp contrast from the run-
of-the-mill awuful stuff is that the narrative commentary to good,
inspired code is always well-formed, grammatically correct and often
witty.
Consider the fellow who's devised his own allocation algorithms using
a Fibonacci series introducing his narrative with "Lieber Leser".
Or the fellow who, in his buffer-management scheme makes reference to
"guru beads". Or the database author who talks about quipus. When
the same fellow was writing proposal text, he was equally engaging.
And it's something that causes me a bit of despair when reading the
'Net-engendered 133T-text of young programmers.