🚀 go-pugleaf

> >  File and function headers should be standardized and should contain
> >enough information. Arguments, description, side effects, and
> >modification history are good starters...
...
> Yes, this is good, but these ideas are also a good source of unnecessary 
> verbosity. I detest when some define template headers like you mention
> which empty fill half of an A4 page...

Erland Sommarskog goes on to outline rules which can fill out the function
header with nearly useless information--how to call it, etc.

People may not realize just how much trouble it can cause.  A few years
back, I saw a procedure-heading standard which was so large and ornate that
it was actually causing people to *avoid* writing procedures!  They were
working on a project which had deadlines (as opposed to lines-of-code-per-
day goals:-), but they were absolutely required to build one of these giant
headers for each function.  As a result, it was often easier to write code
in-line to perform the identical function in several different places than
to split it out into a separate procedure.

Write your own moral--something about programmers taking the easiest path
so style rules should encourage the easiest path to be the same as the
right one.
-- 
Dick Dunn      UUCP: {ncar,cbosgd,nbires}!ico!rcd       (303)449-2870
   ...If you get confused just listen to the music play...