[phobos] Initial Phobos style guide proposal
Jonathan M Davis
jmdavisProg at gmx.com
Wed Mar 30 20:00:36 PDT 2011
It's become clear that we need at least a basic style guide for Phobos. While
some of our coding conventions are clear and consistent, others vary depending
on who's writing the code, and more importantly, new folks writing code for
Phobos (be they new Phobos devs or simply writing code to be reviewed for
inclusion in Phobos) need to be aware of the coding conventions that we
follow. So, I've put one together based on what has previously been discussed,
what we generally do in code, and what the online style guide says (though all
I did with that for the most part was take some of its nicer points that we
pretty much follow anyway).
This is obviously not set in stone. Rather it's the starting point for a
discussion. In the first two sections (naming conventions and formatting
conventions), _most_ of it has been agreed upon by the Phobos devs in general,
as I understand it (though there are some areas - such as line length - which
have _not_ been agreed upon). The last section, general coding guidelines, is
mixture of what we already do and what Andrei has said that he wants to be the
case (though I did tweak some of what he said - e.g. one of his posts implied
that there shouldn't be _any_ empty lines in a function which leads to highly
unreadable functions IMHO), so that is _definitely_ an area which is up for
discussion. It might also be a bit long with items that are obvious enough
that we can remove them, though the idea is to make what we expect in Phobos
code clear.
These are intended to be general guidelines which are followed most of the
time but can be broken within reason (though hopefully that's relatively
rare).
============
Naming conventions
------------------
- Type names are camelcased and begin with an uppercase letter.
- Function and variable names and named values (including enum values) are
camelcased and begin with a lowercase letter.
- Module names are all lowercase without camelcasing.
- Private member variables begin with an underscore.
- With templates, if they're for a type or result in a type, use the naming
conventions for type names. If they generate a value, then use the naming
conventions for variables. For template mixins, use the naming conventions
for type names.
- Try to make names clear and descriptive, but avoid overly long names.
Shorter names which are still appropriately descriptive are preferred.
Formatting Conventions
----------------------
- Don't use tabs. Use spaces.
- Indenting is 4 spaces.
- Braces go on their own line and line up.
- Commit code with unix line endings (though what you use in your editor
is irrelevant).
- Try to make lines not exceed 80 characters, but it's not a hard limit.
If it harms code readability to restrict it to 80 characters, then exceed
80 characters, but if you go much beyond 80 characters, you really should
break the line up.
General Coding Guidelines
-------------------------
- Don't put multiple statements on the same line.
- Restrict the scope of variables as much as reasonably possible and declare
them as late as reasonably possible.
- Use enums for manifest constants, not const or immutable.
- 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.
- Avoid having 2+ empty lines in a row and reasonably minimize how many empty
lines are within a function.
- Try to fit functions loosely on one editor page.
- 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).
- Avoid meaningless aliases. Use aliases when reasonable, but we don't want
to pollute the namespace with unnecessary aliases.
- Prefer to follow the convention that [] and * go with the type name rather
than the variable name (e.g. int* a; instead of int *a;).
- Do not use Hungarian notation.
- All public declarations should have proper ddoc documentation.
- If you need to use a version block for documentation, use version(StdDoc),
not version(D_Ddoc).
- DDoc documentation should be generatable for all OSes, so if you have
multiple versions of a function for differing OSes or if a function doesn't
exist on all OSes, then either put the version blocks within the function
or use a version(StdDoc) with a declaration of the function (without a body)
and the documentation.
- Unit test as much as is practical.
- Generally avoid using else with versions (as in else by itself, not
else version(x)) with version blocks unless you use static assert(0) in
the else block. We want to avoid cases where a new OS is used with Phobos
and it uses the version block for another OS without a programmer properly
looking at it and verifying that it's valid for the new OS.
- Make functions pure, nothrow, and const (if it's a member function) as much
as reasonably possible, so that they work with pure, nothrow, and const
code.
- Make as many function parameters const (or scope) as reasonably possible so
that you can pass const and immutable values to them.
* Note: The rules in this style guide are guidelines which we want to be
generally followed so that we have consistent code in Phobos, but
they are not generally hard-and-fast rules which can never be broken.
They are guidelines that we wish to follow. So, you can break them
_within reason_ but should generally follow them.
============
Personally, I'd prefer a line's character limit to be more like 100 (if not
more). I also like putting two empty lines between functions (as the old,
online style guide says to do), so the restriction eliminating two empty lines
in a row doesn't appeal to me. I also am not fond of the tendency of some
(such as Andrei) to eliminate all extra vertical space within a function
(though I do understand not wanting to have tons of empty lines in functions),
and that combined with restrictions on line length is a nasty combination for
code readability. _Most_ of the rest, I agree with. However, there are
obviously going to be compromises made by pretty much everyone involved. What
we need is a general consensus that we're generally willing to code to and
which is clear.
So, that's my initial draft. After we've discussed it a bit and are more firm
on what we want to do, I can create a version using DDoc which is nicer
looking and can be put on the website if we want to.
- Jonathan M Davis
More information about the phobos
mailing list