header layout agreements

[Dimitrie O. Paun]

On November 1, 2002 07:12 am, Christian Neumair wrote:
> Comments on that, please :)

Well, here it goes:
  -- I don't care much about DESC. In fact, it should be
     painfully obvious what the file is for in 99.99% of
     the cases. If you feel like adding it, sure, go ahead,
     you can add a small blurb, without the DESC tag. It's
     clear what it does, or the description is b0rken :)
  -- I don't think FUNC section is a good idea. It server
     no purpose (almost all we do is documented by MS, just
     go read that docu), and besides, can be automatically
     extracted from the source. I think we should add the
     *absolute* minumum docs, and not more: this way people
     will actually add the essential things, easier to
     maintain, less chance of bitrot. This one fails the test.
  -- The TODO & BUGS sections are very useful (I mean, more
     than words can say), assuming they define a close universe.
     That is, they document all that's left to do, so I don't
     have to go understand all code to figure this out.
     This is where people with good domain knowledge should
     do a quick brian dump. It's not much work, and it helps
     other developers plenty. A good way to keep track of
     progress, and status, BTW.

-- 
Dimi.