<html><body><div style="color:#000; background-color:#fff; font-family:arial, helvetica, sans-serif;font-size:12pt"><div><span>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.</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>Also, can we standardize the comment style, at least for ddoc comments? I've seen a few different styles
in phobos. My favorite is:</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>/**</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span> * comment</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span> */</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family:
arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>or</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><span>/++</span><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span> + comment</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span> +/<br></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>I do not like
this:</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>/**</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>comment</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>*/</span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br><span></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color:
transparent; font-style: normal;"><span>because it's more difficult to distinguish commented lines from normal lines.<br></span></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;">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");</div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><br></div><div style="color: rgb(0, 0, 0); font-size: 16px; font-family: arial,helvetica,sans-serif; background-color: transparent; font-style: normal;"><span>-Steve<br></span></div><br><div><blockquote style="border-left: 2px
solid rgb(16, 16, 255); margin-left: 5px; padding-left: 5px;"><div style="font-family: arial,helvetica,sans-serif; font-size: 12pt;"><div style="font-family: times new roman,new york,times,serif; font-size: 12pt;"><font face="Arial" size="2"><hr size="1"><b><span style="font-weight: bold;">From:</span></b> Jonathan M Davis <jmdavisProg@gmx.com><br><b><span style="font-weight: bold;">To:</span></b> phobos@puremagic.com<br><b><span style="font-weight: bold;">Sent:</span></b> Wednesday, March 30, 2011 11:00 PM<br><b><span style="font-weight: bold;">Subject:</span></b> [phobos] Initial Phobos style guide proposal<br></font><br> 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><br>- 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><br><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><br>- 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><br>- 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 ymailto="mailto:phobos@puremagic.com" href="mailto:phobos@puremagic.com">phobos@puremagic.com</a><br><a href="http://lists.puremagic.com/mailman/listinfo/phobos" target="_blank">http://lists.puremagic.com/mailman/listinfo/phobos</a><br><br><br></div></div></blockquote></div></div><br>
</body></html>