<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div>
<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; ">-- <br>/Jacob Carlborg</span>
</div>
<br><div><div>On 31 mar 2011, at 05:00, Jonathan M Davis wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div>It's become clear that we need at least a basic style guide for Phobos. While <br>some of our coding conventions are clear and consistent, others vary depending <br>on who's writing the code, and more importantly, new folks writing code for <br>Phobos (be they new Phobos devs or simply writing code to be reviewed for <br>inclusion in Phobos) need to be aware of the coding conventions that we <br>follow. So, I've put one together based on what has previously been discussed, <br>what we generally do in code, and what the online style guide says (though all <br>I did with that for the most part was take some of its nicer points that we <br>pretty much follow anyway).<br><br>This is obviously not set in stone. Rather it's the starting point for a <br>discussion. In the first two sections (naming conventions and formatting <br>conventions), _most_ of it has been agreed upon by the Phobos devs in general, <br>as I understand it (though there are some areas - such as line length - which <br>have _not_ been agreed upon). The last section, general coding guidelines, is <br>mixture of what we already do and what Andrei has said that he wants to be the <br>case (though I did tweak some of what he said - e.g. one of his posts implied <br>that there shouldn't be _any_ empty lines in a function which leads to highly <br>unreadable functions IMHO), so that is _definitely_ an area which is up for <br>discussion. It might also be a bit long with items that are obvious enough <br>that we can remove them, though the idea is to make what we expect in Phobos <br>code clear.<br><br>These are intended to be general guidelines which are followed most of the <br>time but can be broken within reason (though hopefully that's relatively <br>rare).<br><br>============<br>Naming conventions<br>------------------<br>- Type names are camelcased and begin with an uppercase letter.<br><br>- Function and variable names and named values (including enum values) are<br> camelcased and begin with a lowercase letter.<br><br>- Module names are all lowercase without camelcasing.<br><br>- Private member variables begin with an underscore.<br></div></blockquote><div><br></div><div>I don't see any reason what so ever to put an underscore in front of member variable. The only reason I would see this as useful is when having getter/setter method with the same name, ie:</div><div><br></div><div>class Foo</div><div>{</div><div> int _foo;</div><div><br></div><div> int foo () { return _foo; }</div><div>}</div><div><br></div><div>But in that case I would still prefer to put the underscore after the name. </div><br><blockquote type="cite"><div><font class="Apple-style-span" color="#000000"><br></font>- With templates, if they're for a type or result in a type, use the naming<br> conventions for type names. If they generate a value, then use the naming<br> conventions for variables. For template mixins, use the naming conventions<br> for type names.<br><br>- Try to make names clear and descriptive, but avoid overly long names.<br> Shorter names which are still appropriately descriptive are preferred.<br><br><br>Formatting Conventions<br>----------------------<br>- Don't use tabs. Use spaces.<br><br>- Indenting is 4 spaces.<br><br>- Braces go on their own line and line up.<br><br>- Commit code with unix line endings (though what you use in your editor<br> is irrelevant).<br><br>- Try to make lines not exceed 80 characters, but it's not a hard limit.<br> If it harms code readability to restrict it to 80 characters, then exceed<br> 80 characters, but if you go much beyond 80 characters, you really should<br> break the line up.<br></div></blockquote><div><br></div><div>I would increase this to something like 100 or 120.</div><br><blockquote type="cite"><div><br>General Coding Guidelines<br>-------------------------<br>- Don't put multiple statements on the same line.<br><br>- Restrict the scope of variables as much as reasonably possible and declare<br> them as late as reasonably possible.<br><br>- Use enums for manifest constants, not const or immutable.<br><br>- Prefer anonymous temporaries to named values within reason.<br><br>- Prefer ? : to if/else within reason.<br><br>- Prefer compact, effective code to verbose code within reason. Make every<br> line count.<br></div></blockquote><div><br></div><div>I completely disagree with this. I don't see why it's so important to save vertical space. I would say prefer readable code to compact code.
Don't be afraid of having long descriptive names of variables and having
vertical space in your code. I don't mean you should put three newlines
between two function declarations but I usually put a newline before and
after statements: </div>
<br>int a;
<br>int b;
<br>
<br>foo();
<br>bar();
<br>
<br>if (a == b)
<br> foo();
<br>
<br>else
<br> bar();
<br>
<br>int c = 3; </div><div><br><blockquote type="cite"><div>- Avoid having 2+ empty lines in a row and reasonably minimize how many empty<br> lines are within a function.<br><br>- Try to fit functions loosely on one editor page.<br><br>- Comments should be high level (describing 3-10 lines) instead of low-level<br> (describing the mechanics of the next line, which are already obvious in<br> code).<br><br>- Avoid meaningless aliases. Use aliases when reasonable, but we don't want<br> to pollute the namespace with unnecessary aliases.<br><br>- Prefer to follow the convention that [] and * go with the type name rather<br> than the variable name (e.g. int* a; instead of int *a;).<br><br>- Do not use Hungarian notation.<br><br>- All public declarations should have proper ddoc documentation.<br></div></blockquote><div><br></div><div>And protected methods as well, they're a part of the API just as much as the public methods.</div><br><blockquote type="cite"><div>- If you need to use a version block for documentation, use version(StdDoc),<br> not version(D_Ddoc).<br><br>- DDoc documentation should be generatable for all OSes, so if you have<br> multiple versions of a function for differing OSes or if a function doesn't<br> exist on all OSes, then either put the version blocks within the function<br> or use a version(StdDoc) with a declaration of the function (without a body)<br> and the documentation.<br><br>- Unit test as much as is practical.<br><br>- Generally avoid using else with versions (as in else by itself, not<br> else version(x)) with version blocks unless you use static assert(0) in<br> the else block. We want to avoid cases where a new OS is used with Phobos<br> and it uses the version block for another OS without a programmer properly<br> looking at it and verifying that it's valid for the new OS.<br><br>- Make functions pure, nothrow, and const (if it's a member function) as much<br> as reasonably possible, so that they work with pure, nothrow, and const<br> code.<br><br>- Make as many function parameters const (or scope) as reasonably possible so<br> that you can pass const and immutable values to them.<br><br><br>* Note: The rules in this style guide are guidelines which we want to be<br> generally followed so that we have consistent code in Phobos, but<br> they are not generally hard-and-fast rules which can never be broken.<br> They are guidelines that we wish to follow. So, you can break them<br> _within reason_ but should generally follow them.<br>============<br><br>Personally, I'd prefer a line's character limit to be more like 100 (if not <br>more). I also like putting two empty lines between functions (as the old, <br>online style guide says to do), so the restriction eliminating two empty lines <br>in a row doesn't appeal to me. I also am not fond of the tendency of some <br>(such as Andrei) to eliminate all extra vertical space within a function <br>(though I do understand not wanting to have tons of empty lines in functions), <br>and that combined with restrictions on line length is a nasty combination for <br>code readability. _Most_ of the rest, I agree with. However, there are <br>obviously going to be compromises made by pretty much everyone involved. What <br>we need is a general consensus that we're generally willing to code to and <br>which is clear.<br><br>So, that's my initial draft. After we've discussed it a bit and are more firm <br>on what we want to do, I can create a version using DDoc which is nicer <br>looking and can be put on the website if we want to.<br><br>- Jonathan M Davis<br>_______________________________________________<br>phobos mailing list<br><a href="mailto:phobos@puremagic.com">phobos@puremagic.com</a><br>http://lists.puremagic.com/mailman/listinfo/phobos<br></div></blockquote></div><br></body></html>