21 Nov
2011
21 Nov
'11
6:57 p.m.
On 21/11/11 10:11 AM, Jason McBrien wrote:
I've found the following to be true:
1 - If you wrote the code, even if it's undocumented, you are going to be
likely to know what it does when reviewed later on
Not everyone agrees with this (e.g. Charles Simonyi*; even prodigies
grow old). Code is *not*, on the whole, self-documenting - at least as
it is written these days. And even if a single method is "obvious"
(let's say it's short and sweet, 5 lines), where is the rationale for
the design of the 900 classes that it nestles in? Does anyone document
and write manuals for huge class hierarchies? Or does everyone just
learn them the slow and painful way by having to maintain them day by
day after the original programmers have left?
2 - If you've modified someone else's code, you probably aren't going to
remember what it does
I've toyed with literate programming - it doesn't work so well when you are
writing code for other people, as the utility of the documentation is
limited by your ability to write technical documentation, and the odds of
the original design being correct is pretty low if you are delivering code
to users.
"Do the simplest thing that could possibly work" doesn't mean
"incorrect
or badly".
You end up going back and re-writing the same code
over and over
again, updating the documentation starts eating up a significant chunk of
time.
My rule for code documentation is to be terse, to the point, explain why
you are doing something as opposed to what you are doing, and only comment
when it's not obvious what's happening. IE Employee.SelectOne(EmpName)
doesn't need a comment, but DataSet.ReverseOrder(SortBy.Date) probably does.
"Readable terseness" is very much undermined by the majority of popular
mainstream languages. No proper macros; no pattern matching; etc, etc...
They do run the spectrum from unhelpful to awful.
--Toby
* - http://www.hackerne.ws/item?id=560185