Re: Documentation

Dale Amon as Operator (root@starbase1.gpl.net)
Thu, 17 Jul 1997 23:49:32 +0100 (BST)

>And after the code freeze deadline has been met, the next deadline,
>with features that have already been promised to customers by the
>salesmen, comes up so quickly there's often little time to clean up
>after the short cuts that were made to meet the *last* code deadline.
>
>This is why being able to read poorly documented code is a very
>important real world skill....

Depends much on the house. I comment as I write and was trained
that way and *enforced* it on my teams.

Anyone who's ever read the old Macro-11 RSX-11m source by DN Cutler
knows what good commercial code looks like. Just because there are
places digging themselves holes to dive into is no excuse for
anyone else to go dig their own deep one. Hell, I even comment
my test programs...

BTW - I lifted my own formatting and coding standards from
a combination of DN Cutler/DEC assembler standards and
some of the CMU/Mach coding standards. Mach is not badly
commented either now that I think about it. If someone is going
to go in and do back-commenting, I'd suggest looking at some
of the standards used there. No sense in reinventing the wheel.

But Cutler was an artist :-)