Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

Re: On comments

by mr_mischief (Monsignor)
on Dec 20, 2010 at 04:21 UTC ( #877945=note: print w/replies, xml ) Need Help??


in reply to On comments

There's been a lot of comparing software development to building erection, machine shops, and other physical construction types of tasks lately. Let me draw some parallels, then, to certain products for those tasks. A furnace, water heater, circular saw, drill press, or welder has more than one type of documentation. Those are located in different places for different audiences and for different purposes. There's the user's manual. That tells people how to use the device day-to-day and where to get optional attachments and expendable replacement parts. Then there's the maintenance manual that covers how to fix broken devices and where to get replacements for the permanent parts of the device the end user shouldn't be bothered to replace. Then there are warning stickers near places where electricity, hot surfaces, moving parts, lasers, or sharp edges cause particular dangers. These are for anyone: the end-user, the maintenance worker or repair shop, or a curious visitor. They draw attention to certain areas to avoid and warn people to be careful around certain parts no matter what their level of intimacy with the device.

A big part of the issue here is that the user and the maintenance programmer can often find the same type of documentation about the program, even though it is for different audiences. That type is prose about how to use features of the program to do things which is found separately from the code. The only difference between this type for the end user and for the programmer is which features are covered. Think of these as the user manual and the maintenance manual for your plumbing and heating fixtures or power tools. For the end user, features of the user interface and how to operate the program are covered. For the maintenance programmer, features of the programmer interface (APIs, data formats, extension mechanisms, callback hooks, and more) and how the parts work together are the topics. Those are definitely features, and they can form what is clearly an interface. Many programmers, especially for a large and complex program, want this sort of documentation ever as much as the end user does. They want the developer interfaces covered with as much care and detail as the end-user interface.

Comments can be documentation, too. They should not be the sort of documentation mentioned above, though. A comment placed locally in a particular section of code should be used only to convey information germane to that local section of code. If there's for example a line that seems superfluous but works around a serious security risk and therefore shouldn't be removed for the sake of speed or efficiency*, it is my opinion there should be a comment about that line right there. If there's some reason a section of code looks crufty because it's working around a bug in a lower layer of software, you probably want to document that right in the code with a comment, too. Think of these comments as "attention" or "warning" labels near the hot, sharp, blinding, or crushing parts of the device.

The comments really shouldn't be the place you document everything a programmer needs to know about APIs and data formats. The POD or external documentation in some other format really shouldn't be the only place an important security, speed, or bugfix hack in the code is mentioned. You might want to mention it there as well, but comments immediately above or to the side of the code the next programmer might try to edit is the safest place to put such "warning label" documentation.

* This actually happened in part of the Linux kernel somewhat recently. A line of assembly code for the AMD and Intel x86_64 processors (which zero-filled a register) was removed which lead to a local root exploit. To someone without proper knowledge, it looked like a wasted CPU operation. The same bug had been fixed in 2007 (CVE-2007-4573) in Linux 2.6.22.7 and was reintroduced at some point. It was rediscovered as a vulnerability in 2010 (CVE-2010-3301). Had there been a clear enough comment close enough to that line in the code, perhaps the vulnerability would have stayed closed.

Replies are listed 'Best First'.
Re^2: On comments
by sundialsvc4 (Abbot) on Dec 21, 2010 at 16:47 UTC

    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...

      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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://877945]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (4)
As of 2020-02-25 07:07 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What numbers are you going to focus on primarily in 2020?










    Results (108 votes). Check out past polls.

    Notices?