sommar@enea.se (Erland Sommarskog) (05/18/88)
Peter J Desnoyers (peter@athena.mit.edu) writes: > File and function headers should be standardized and should contain >enough information. Arguments, description, side effects, and >modification history are good starters. For protocol or compiler >stuff, references (to defining documents) are useful as well. Someone >should create templates for these things, and maybe standard editing >macros like box-region. 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. This makes it much harder for the procedure to fit within this one page, which is very desireable to help up the overview. I've seen headers where you should describe how to call the procedure, something I see no use for. And every parameter description takes at least two lines. And a lot of stars or whatever for elegant frames. The way to go is to not include more information than necessary. If there are no side effects, don't waste three lines telling that, just omit it. If you can describe the meaning and modes of the parameters in the description, or if they are obvious, save those lines. A thing I usually mention in the header is internal procedures, since they tend to isolate the header from the body. If you know that there are three internal procedures, you probably have to advance three pages to get the body to the one your looking at. (Of course you have form feeds bewteen all procedures, haven't you? :-) Descriptions on module level can be longer since you often can save a page solely for them. But still I dislike seeing standardized headers, when filled in 70% is still the template. -- Erland Sommarskog Take C, a third class language ENEA Data, Stockholm and a C programmer, i.e. a third class programmer sommar@enea.UUCP => A ninth class program, a C program.