httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Richards <p.richa...@elsevier.co.uk>
Subject Re: Style guide
Date Tue, 02 Jul 1996 13:20:36 GMT
Ben Laurie writes:
 > Paul Richards wrote:
 > 
 > On second thoughts, I don't think that any commenting requirements should be
 > a coding style issue.

I'll back off on a lot of the points but not comments. We should
mandate a certain level of commenting. I had to work out what
check_user_access() does by reading every line of code and checking
through all the structures and functions used to see how it works, a
paragraph at the top that said what it's basic functionality was  would
have saved me a lot of time.

The comment says

/* Checking ID */

which didn't exactly tell me what the function *actually* did.
Commenting code is *IMPORTANT*.

 > And many other things that have not been listed.

I think our document should also contain real code showing the style
implicitly in the same way rather than just 10 or so rules that only
cover specific points.

 > > > > #define MACRO(x, y) {                           \
 > > > >     variable = (x) + (y);                       \
 > > > >     (y) += 2;                           \
 > > > > }    
 > 
 > Yes. I have the Explain macro which I want to look like a function call
 > (because it is).

That's not good practice. If something is a macro don't hide the fact, it
makes it far more difficult to work out how things work, it's really annoying
to go searching for a function declaration and then find it's some macro
defined in a header file.

 > > > > /*
 > > > >  * All major routines should have a comment briefly describing what
 > > > >  * they do.  The comment before the "main" routine should describe
 > > > >  * what the program does.
 > > > >  */
 > > 
 > > This is actually important. There's very little documentation of routines
 > > in the code.
 > 
 > Not a style issue, IMO.

I disagree fundamentally.

 > I'm not fantastically interested in tiny points of style. My main interest is
 > in where the braces and indents go. The rest can go to hell as far as I'm
 > concerned.

My concern is making the code understandable, not make it look
asthetically pleasing, that's what a style guide should aim to achieve,
make it clear to someone who's never looked at the code before what is
basically going on so they have some idea what things do before they
get into the detail of the code. Clear comments are essential,
non-ambiguity of whether something is a macro, function, enum type or
variable is also important.

Mime
View raw message