[phobos] Initial Phobos style guide proposal

[Jacob Carlborg]

On 31 mar 2011, at 19:30, Jonathan M Davis wrote:
> I do think that we don't want tons of extra space in our code, but I 
> definitely favor having some blank lines in code - though I'd never put a 
> blank line before an else like that. I think that trying to be particularly 
> restrictive about vertical space leads to code which is harder to read (and 
> being restrictive about both line length and vertical space at the same time 
> is definitely a bad combination for readability). I do think that trying to 
> keep functions to a page of code or so (however long that's supposed to be) is 
> generally a good idea, but I confess that I do not really understand Andrei's 
> preference for incredibly compact code. I find it harder to read and maintain.

I absolutely think that I function should fit within a page of code but the way to do that is NOT to write more compact code vertically. It's to split the function in several smaller ones, split the classes in smaller ones and split the modules smaller ones. That is clearly something that Andrei and Walter doesn't seem to understand.

> I would think that ideally we'd want code that is both short and clear, but 
> those are often contradictory requirements, and personally, I tend to prefer 
> clear to short. Andrei seems to prefer short, or at least finds more compact 
> code to be clearer and easier to read than some of the rest of us do. So, I'm 
> not quite sure what we want to do about this. It seems like some sort of 
> compromise is required.

I agree with you here.

>>> - 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.
>> 
>> And protected methods as well, they're a part of the API just as much as
>> the public methods.
> 
> Good point.
> 
>>> - 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
> 
> Overall, I get the impression that most of the style stuff that Phobos devs 
> have expressed interest in having rules on are in the public API whereas what 
> Andrei seems most interested in is the internal coding style. So, I don't know 
> where we want to go with this. Personally, I think that consistency the public 
> API is by far the most important thing, but we also don't want a complete 
> hodge-podge in the code itself. I'm generally inclined not to get all that 
> picky about style rules such as the number of characters per line or the exact 
> naming of private member variables.
> 
> However, we need to actually get a decent discussion and agreement from the 
> Phobos devs as a whole, otherwise it's just a few of us determining it for the 
> group as a whole, and we could end up with something that only a few of us 
> like (or are willing to stick to). Once we've agreed and have a final 
> document, hopefully we can pretty much drop the issue and just point people to 
> the document in the future.
> 
> - Jonathan M Davis
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos


Yes we should try to focus on the public API.

-- 
/Jacob Carlborg