Re^2: On comments

in reply to Re: On comments
in thread On comments

Excellent thoughts.

Another, often-overlooked source of “documentation” is the change-history in the version control system, and any defect-reporting system records that you may have. (And you do have them and you do use them, don't you?... Ahh, yes. Of course you do. Of course.)

When you’re fixing a bug that was reported in the defect tracking system, record the defect-number in the comment. When you check-in the change, update the defect record to show it. This lets you perceive exactly what has changed in a module over time, and why.

This is a “dynamic” form of information, analogous to the “running log” that was routinely kept in the engine-room, or the “captain’s log” (“Stardate 4523.3 ...”) that was kept on the bridge.

Bonus Question: what happened on that stardate? Extra Vulcan-points if you don’t have to Google it...

Replies are listed 'Best First'.
Re^3: On comments by oko1 (Deacon) on Dec 22, 2010 at 06:12 UTC
As it happens, in addition to being a Perl geek, I'm a sailboat captain (currently heading for the Bahamas along the US East Coast, chasing the warm weather.) One of the first things that crew aboard my boat learn is that any actions other than the obvious and expected ones must be logged - and anyone either coming on watch or about to do any kind of work must review the log. In addition, anything requiring general notice (e.g., work in process) is specially flagged - e.g., if someone's down in the engine compartment and changing the alternator belt, then not only is the starting battery switched out of the circuit, but the starting key is taken out of its slot and secured to its hook with a red Velcro strap. Otherwise, there's nothing to stop someone from thinking "oh, they forgot to flip the battery switch to 'Start'!" and flipping it on, then cranking the engine. Shipboard communication, much like the language of science, has been developed over a period of centuries and for much the same reason (plus the extra bit of awareness that you're likely to maim or kill someone, or yourself, if you get it wrong.) That's why stories like that kernel bug being restored make me itch; that's precisely the kind of miscommunication that shipboard procedures are intended to prevent. -- "Language shapes the way we think, and determines what we can think about." -- B. L. Whorf	[reply]

Replies are listed 'Best First'.

Re^3: On comments
by oko1 (Deacon) on Dec 22, 2010 at 06:12 UTC

As it happens, in addition to being a Perl geek, I'm a sailboat captain (currently heading for the Bahamas along the US East Coast, chasing the warm weather.) One of the first things that crew aboard my boat learn is that any actions other than the obvious and expected ones must be logged - and anyone either coming on watch or about to do any kind of work must review the log. In addition, anything requiring general notice (e.g., work in process) is specially flagged - e.g., if someone's down in the engine compartment and changing the alternator belt, then not only is the starting battery switched out of the circuit, but the starting key is taken out of its slot and secured to its hook with a red Velcro strap. Otherwise, there's nothing to stop someone from thinking "oh, they forgot to flip the battery switch to 'Start'!" and flipping it on, then cranking the engine.

Shipboard communication, much like the language of science, has been developed over a period of centuries and for much the same reason (plus the extra bit of awareness that you're likely to maim or kill someone, or yourself, if you get it wrong.) That's why stories like that kernel bug being restored make me itch; that's precisely the kind of miscommunication that shipboard procedures are intended to prevent.

--
"Language shapes the way we think, and determines what we can think about."
-- B. L. Whorf

[reply]

In Section Meditations