[phobos] Initial Phobos style guide proposal

Thu Mar 31 06:29:45 PDT 2011

One thing I've noticed about std.container, and it makes it very hard for me to read:  Putting all ddoc comments with no indentation.  In particular, I have a very hard time seeing where a class or struct ends.  Andrei, there must be a good reason for you to do this, can you explain that?  I'd really prefer that the comments are put at the same indentation as the code being commented.

Also, can we standardize the comment style, at least for ddoc comments? I've seen a few different styles in phobos.  My favorite is:

/**
 * comment
 */

or
/++
 + comment
 +/

I do not like this:

/**
comment
*/

because it's more difficult to distinguish commented lines from normal lines.

Also, in the section saying "don't use else for version statements" I think it's acceptable and actually recommended to use else assert(0, "Unsupported OS");

-Steve

>________________________________
>From: Jonathan M Davis <jmdavisProg at gmx.com>
>To: phobos at puremagic.com
>Sent: Wednesday, March 30, 2011 11:00 PM
>Subject: [phobos] Initial Phobos style guide proposal
>
>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
>_______________________________________________
>phobos mailing list
>phobos at puremagic.com
>http://lists.puremagic.com/mailman/listinfo/phobos
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/phobos/attachments/20110331/acc1f161/attachment.html>