header layout agreements
Dimitrie O. Paun
dpaun at rogers.com
Sat Nov 2 09:48:23 CST 2002
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.
More information about the wine-devel