On Jun 3, 2006, at 5:35 PM, Andrew Lentvorski wrote:
So, what is proper documentation, pray tell?
worst case? At a minimum, an explanation in the comments of the code explaining what a block of code does. Personallly, I tend to put in the comments first to remind myself what it is I'm trying to do, then I start fleshing out blocks of code for each task, and if I had to change tactics or replace an algorithm, update the comments to fit. It really doesn't take that much longer than doing the code only, and makes it much easier to understand.
Any time you think you're being clever in code, comment your cleverness. This has saved me time on fixing bugs in my own code many months later. I came up with a really nice one-line snippet of code for whatever it was doing, and six months later spend the better part of a day figuring out why it wasn't handling a new case. Sure, the comment explaining it would have been as long as this paragraph, but man it would have saved me time.
Better documentation: if you're project provides a plug-in archetecture, at least friggin document the API instead of relying on people to read the code of your "simplest" plugin to get it right, especially if your simple plugin isn't commented or documented at all. Java, Perl, Ruby and a host of other languages provide built-in facilities for doing documentation with the effort level of simply putting good comments in your code. No excuse to not use it.
And how do you keep it synchronized with the code?
Honestly? Discipline. If you can't be bothered to write code that's well-commented and/or minimally documented, I'll send it back to you. Why? Because I am too busy to spend a whole day trying to figure out what the hell a particular method is doing and why it's breaking, or have one of my staff spend two days doing the same thing all over again.
The time it takes to, at a minimum, put meaningful and useful comments in code is well worth the avoidance of many times more effort to fix/patch/extend the code later.
Gregory -- Gregory K. Ruiz-Ade <[EMAIL PROTECTED]> OpenPGP Key ID: EAF4844B keyserver: pgpkeys.mit.edu
PGP.sig
Description: This is a digitally signed message part
-- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
