On 3/30/11 2:47 PM, Jonathan M Davis wrote:
I've tried to get Andrei to agree to a style guide a few times, but he's
generally pushed back on it. I definitely think that we should have one if we
want to actually have a consistent style, but thus far, he hasn't agreed to
have one.

I think that's not representing my viewpoint quite accurately, but getting to the bottom of whatever misunderstanding was there is not important.

It would be helpful to have a broad style guide. The existing one is a good start and is in fact already observed by much of Phobos (and in particular by most of my code). The problem with writing a more elaborate guide is finding the person(s) with the time and inclination to write a draft, get it vetted by the major contributors, and take it to completion.

For my money, just take the first that applies:

- Is it a function name? Use thisStyle.

- Is it a value (be it constant or variable)? Use thisStyle.

- Is it a type? Use ThisStyle.

- Is it a module name? Use this_style.

Beyond naming:

- Define variables as late as possible.

- Define constants and other names scoped appropriately.

- Prefer anonymous temporaries to named values within reason.

- Prefer ? : to if/else within reason.

- Prefer compact, effective code to verbose code within reason. Make every line count.

Nitpicks that 9 people have 10 opinions of:

- No 2+ empty lines please. Within a function, an empty line at best should be replaced by a comment describing the meaning of the next block.

- Try to fit functions loosely on one editor page.

- Brace on its own line. (In fact I don't care much either way, but this is the way the majority of the code is.) Note that this does cost more vertical space so it somewhat clashes with the previous point.

- Please avoid > 80 columns unless you feel it induces sterility in the long term.

- No tabs please.

- Comments should be high level (describing 3-10 lines) instead of low-level (describing the mechanics of the next line, which are already obvious in code).


Thanks,

Andrei

Reply via email to