Documentation, Our Responsibility for The Party
The Hacker's Point Of View
By WWWWolf

Documentation is NOT a Bad Thing. Really. Feel free to frown on flowcharts, but never underestimate the importance of written word. I mean, what will you rather do:

1. strings SomeClass.class

   or,

2. lynx docs/SomeClass.html

I bet most will rather choose the latter. (Trust me. I've often needed to do the first, and it Wasn't Fun. And don't even mention javap. We didn't had that luxury.)

Documentation of computer programs is an important matter. Infortunately, it's not entirely painless.

To make good programs, you need plans - if you write the goals of programming product down first, in any even remotely understandable form, it's often easy to start writing the program. It's a lot easier when you know what you're doing.

Also, if you write plans down, others may "get" what you're supposed to do. This is often desirable. You may want to learn something like UML to make readable designs.

Then, now, you have to code the program. You have the design penned down somehow; how to document the actual code? Well, the usual way is slapping around comments like crazy. =) To document your API, use an automated documentation generation system. If you're programming in Java, you already have javadoc tool to spit out HTML documentation - to comment anything relevant, just /** comment it like this */.

Documenting code is often important - this way, you don't need to read your code much later and wonder what was your Great Idea when you thought of that convolution that hangs before you on the screen...

To survive the documentation hell, remember the Mantras:

• "If I make this, The Management won't start whining."
• "Yes, it might help me later."
• "It will help others."

Those three phrases get forgotten too easily...

Try to remember those things, and you'll see the code will get documented almost unnoticedly. =)

Also, you can try this, erm, shock excercise: Take a decompiler. Decompile something. Try reading it. Bet you won't be too excited to start editing that code. Now take any program that is well documented. I bet you feel it's much more interesting to tinker with. =)

Some programs that may help you a lot:

• Argo/UML - Fun-to-use CASE program... Oh, I wish this would generate different languages too in addition to Java, but that's a minor issue.
• DOC++ - If you find documentation pain, at least comment your code so that bulk of the documentation - the documentation for APIs, class interfaces, and so on - can be generated automatically.

documentation n.

The multiple kilograms of macerated, pounded, steamed, bleached, and pressed trees that accompany most modern software or hardware products (see also tree-killer). Hackers seldom read paper documentation and (too) often resist writing it; they prefer theirs to be terse and on-line. A common comment on this predilection is "You can't grep dead trees". See drool-proof paper, verbiage, treeware.

--The Jargon File version 4.3.1, ed. ESR, autonoded by rescdsk.

One of the better comments on documentation appears in Ed Post's classic essay, "Real Programmers Don't Use Pascal":

If there is not enough schedule pressure on the Real Programmer,
he tends to make things more challenging
by working on some small but interesting part of the problem
for the first nine weeks,
then finishing the rest in the last week,
in two or three 50-hour marathons.
This not only impresses the hell out of his manager,
who was despairing of ever getting the project done on time,
but creates a convenient excuse for not doing the documentation.