Granted, I'm not committing (yet?), but that doesn't keep me from voicing an
opinion, right? :)
> 1.2. VARIABLE NAMES
> some variables are named with the CamelCase convention - capitalizing
> the beginning of the word. Other use the word_separated_by_underscore
> convention. Are there other conventions? Which one do you favor?
> variable names should be clear and descriptive. no contractions, maybe
> with a few listed exception, e.g. Pano instead of Panorama. Any more
> exceptions?
Support James' comments re: LeadingCaps for classes/structures/typedefs, and
favoring mixedCase for variables. For functions, I always like the visual
distinction between public and private methods, if only to save a
consultation to intellisense or the header file. Using LeadingCaps for
public functions, mixedCase for private/protected/internal seems to offer
some visual distinction, but that's more a personal preference thing :)
I'm a fan of mixedCase over underscore_insertions_for_words myself, if only
to save the keyboard extension to the underscore. Readability wise I think
they're fairly equal. The only question comes when using acronyms (eg:
sqlVar vs SQLVar vs sQLVar), but I don't know how much of a problem that is.
I haven't seen many variables that have that problem in the codebase, and it
doesn't seem like it'd need to be hammered out now...
> 1.3. FUNCTION NAMES
> should functions follow the same conventions as variables? or a
> different one?
> function names should be descriptive. no contractions, maybe with a few
> listed exception, e.g. Pano instead of Panorama. Any more exceptions?
Agree with James' comment that whatever contractions are acceptable, they be
used exclusively.
> 3. SPACING AND INDENTATION
> 3.1. BRACES
> there are many different indent styles [3]. I am personally used to
> 1TBS
> [4] (like the Linux Kernel), but I recently heard good arguments to
> adopt Allman style [5], which puts the brace associated with a control
> statement or a function on the next line, indented to the same level as
> the control statement. I am ready to go Allman. Or maybe you want to
> suggest other alternatives? Which one do you prefer?
I always find 1TBS to be readable. The most helpful thing is the requirement
that single-line conditionals always include braces. Had too many bugs
working in teams where one dev would use a short construct, and either
between merging or sloppy devs, a second statement would be added that
screws up the code.
eg:
if (condition)
doSomething();
becoming
if (condition)
doSomething();
doSomeOtherThing();
instead of
if (condition) {
doSomething();
doSomeOtherThing();
}
The problem I have with Allman is that I've seen too many bugs where the
code ends up like
if (condition);
{
doSomething();
}
See the error? The extra ; accepted by all the compilers I've ever used,
ends up causing the { } to always be executed. It can be a real pain to
trace through those in complex systems to find out who added the extra ;
when typing
> 3.2. TABULATORS
> use spaces instead of tabulators (to maintain consistency across
> editors). use four spaces for one indentation. or are there other
> preferences?
Spaces, tabs, it's all the same to me. Visual Studio can be a pain when
adjusting between the two, but it's doable. My own preference is "Tabs are
used for logical columns, spaces are used for alignment", but that's not
exactly easy to enforce :) (Of course, a diff usually reveals right away if
things are off). It's only really an issue if column width is also being
fixed - since artificial wrapping is often necessary in those cases.
void foo()
{
<tab>if (someLongCondition
<tab> && otherLongCondition
<tab> || someOptionalCondition) {
<tab><tab>doSomething();
<tab><tab>if (didSomething) {
<tab><tab><tab>doSomethingElse();
<tab><tab>}
<tab>}
}
> 3.3. SPACES
> I would not go into that much detail. or maybe we should adopt/adapt a
> strict coding guide like [2]?
Personally find it readable to use spaces before the parenthesis after
control statements, but not to use spaces before the parenthesis after
functions.
eg:
fn(foo, bar) / x(y) / y(z)
if (condition) / while (condition) / else (something else)
and use spaces after commas
fn(foo, bar, baz)
I find it less readable when the extreme is taken
fn( foo, bar, baz ) or worse fn( foo , bar , baz ), which I've seen both in
projects.
> 3.4. LINE ENDS
> Unix/Linux line ending (Windows and OSX users have to adapt)
Um, is there any reason we're not just using
svn propset svn:eol-style native?
Seems like it solves the problem right there and everybody wins :) I've used
it on all my projects in the past, multiple platforms, and it always works
out. Also handles cygwin in Windows fine (uses LF, like you'd expect from a
posix layer, not CRLF, like Windows)
http://svnbook.red-bean.com/en/1.1/ch07s02.html
> 4. COMMITTS
> It is tempting to clean up old code while fixing bugs or adding new
> code. Please don't - it makes the committ (diff!) much more difficult
> to
> read / understand.
> Keep style clean up committs separated and mention them as such in the
> log message.
Seconded!
Any comments on the use of goto / case labels? It seems like that would be
one of the religious things to hammer out - Is goto considered harmful? Is
considering goto harmful harmful? Is considering goto harmful being
considered harmful harmful? (http://en.wikipedia.org/wiki/Considered_harmful
)
Personally, I'm also a big fan of warning-less code. I'm not talking about
MSFT's annoying _CRT_SECURE_NO_WARNINGS crap, but the warnings that get
emitted when you end up casting int -> size_t and the like, trying to keep
track of all that mess. It's not that bad now, but might help for new code
:)
