On 10/2/2015 8:58 PM, rbowman wrote:
On 10/02/2015 11:12 AM, Don Y wrote:
I have my VCS put a one-line revision summary in the header commentary
but have moved most of my real comments out of the body of the code.
I figure people can *read* code to see what is being done (unless I'm
doing something insanely tricky) so no need to restate the obvious.
Let the code tell what *it* is doing; let the "offline" comments tell
*why* it's doing it!

Use the source, Luke. We have tech writers doing documentation but when the QA
or Ops people ask me a question i usually head right to the source. It doesn't
lie about what it's doing.

The problem is that you can't (practically) say much in the code's
commentary. It's limited to text (no real graphics, multimedia, etc.).

So, if I tell you that this piece of code implements the "a" in "mash"
sound, how do you UNAMBIGUOUSLY know what that means? If you're
from the midwest/Ohio valley areas, chances are, you pronounce
this as "MAYSH"; I, OTOH, pronounce it similar to the "a" sound in "at"
(not "ATE")

Likewise, I can't easily explain why I've implemented a resonator in
a particular way without a long description of the performance tradeoffs
of other, more straightforward approaches. Or, a detailed analysis of
the error budget in each approach, etc.

Put these sorts of things *in* the code and folks' eyes gloss over
before they get to main()...

Also, removing the bulk of the commentary from the code means you can fit
more (code!) on a "page". I really like the "make a complete thought
fit on a single page" philosophy.

[I wrote a driver for half-inch, 9-track tape many years ago -- the
sort of cheesy tape drives you saw in 1960's sci-fi movies? A big
part of the project was sorting out the roles of the various bits of
electronics in a "tape subsystem": there's a "controller"/interface
in the host computer; tape "transports" that actually have the tape
reels, read/write/erase heads, etc.; and a "formatter" that is
the brains of the subsystem -- controlling up to 4 transports. The
first four or five, single-spaced pages of the driver were a detailed
description of these roles -- essential so you knew why the driver *could*
do some things -- like "read reverse" -- and why it could support
*certain* operations in parallel, but not others. Once you understood
the roles of the various components in the subsystem, it made sense.
Without that basic foundation, the code looked like a hodgepodge of
assorted optimizations -- hile MISSING certain other optimizations that
you might think *should* be possible!]

I also tend to be very disciplined in how I write -- I don't try to save
keystrokes as if they were made of gold. E.g., lots of parens to
make operator precedence explicit (so folks don't see what they *think*
they see but what the compiler *will* see); lengthy identifiers (yes,
they include vowels so you're not wndrng wht thy hppn 2 b!); and other
"stilted" constructs that are a throwback to my hardware background
(e.g., "&buffer[0]" instead of "buffer")

Man after my own heart. The older I get, the more verbose my code gets. We had
one guy who must have thought he'd get billed by the character. The first time
I saw his code it took me a while to figure out what ary was.

My hardware designs are similarly highly structured. E.g., I tend
to favor fully synchronous implementations so "CLK" goes EVERYWHERE
with the control logic acting mainly to *enable* particular actions
"on the next CLK edge".

I had a buddy take over a gate array design I was working on. When
I touched base with him a few weeks later and asked if he'd had
any problems, he said, "It took me a while to sort out what you were
doing. But, once I saw how you approached each module, it all was
very obvious!"

I figure that was a compliment.

I eschew single letter identifiers preferring, instead, more informative
names: iterator, index, row, column, etc. I find it makes it easier to
"read" (subvocalize) the code and impart meaning to it in the reading.

He also constructed this, er, thing to parse a homegrown configuration language
that was mostly generated by macros. I forget if it was Kernighan or Ritchie
who said if they'd realized what people would do with macros they would have
never made it into the language. He also managed to incorporate lex, yacc, and
a couple of big, smelly, hairy bisons into the mess. I think every non-trivial
project has areas of the codebase where everyone fears to tread, and that's one
of them.

By putting all the "explanation/rationale" in external documents, when
I approach a "here there be dragons" area in the code, I can simply
state that ("Here there be dragons") and point the reader to the applicable
portion of the accompanying document for the questions he *should* be
asking -- but probably hasn't realized, yet -- along with their explanations.

I also try to make those documents "drive" the code. E.g., I have
a document that enumerates the various "rules" (templates) that
my TTS code uses to convert graphemes to phonemes. This document
uses "industry standard" (linguistic!) symbols for the sounds
involved (e.g., the schwa sound is a "rolled" 'e') as someone with
*that* sort of training would be the logical target of such a document.
Modifying the tables in that *document* causes the const structs that
are embedded in my code to reflect those changes -- without requiring
the developer (coder) to understand their significance, encoding, etc.

(Why does the 'w' sound change in "why", "what", "which", "women", "where",
"we", etc.?)

He had been a CS instructor at the local U and some of the people who took his
classes said he was a stickler for comments, but he certainly didn't practice
what he preached.