<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"><html><head><meta name="qrichtext" content="1" /><style type="text/css">p, li { white-space: pre-wrap; }</style></head><body style=" font-family:'Sans Serif'; font-size:10pt; font-weight:400; font-style:normal;">In compiz++ I've made few little changes that do not follow the our previous coding style:<br>
- allow variable definition in "for" loops:<br>
for (int i = 0; i &lt; foo; i++)<br>
In the "C" version of compiz we've tried to follow the C89 rules, but this is not necessary anymore and should improve readability.<br>
- define variables not at the top of a function:<br>
For references we have to define a variable at the point where it gets initialised. I would like the keep the "define the variables at the top of a function" style, but we should allow "in body" variable definition, at places where it improves readability of the code.<br>
- indent "case" statements inside of "switch" statements:<br>
in the "C" version of compiz we aligned the case statements at the same level like its switch statement:<br>
switch (foo)<br>
{<br>
case foo1:<br>
    break;<br>
case foo2<br>
    break;<br>
}<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>I think that indenting the "case" statement is a better style here:<br>
switch (foo)<br>
{<br>
    case foo1:<br>
        break;<br>
    case foo2:<br>
        break;<br>
}<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>Another style rule that I would like to add to our coding style is to provide a consistent system to mark differences between function local variables, function parameters, class member variables and global variables.<br>
I have already two possible solutions here:<br>
Solution 1:<br>
postfix member and global variables with a "_"<br>
prefix function parameter with a "_"<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>Solution 2:<br>
prefix member variable with "m_"<br>
prefix global variables with "g_"<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>For my diploma thesis I'm currently working on a C++ tool that already uses the first rule, and I've realized that it really improves readability of the code, because it's pretty clear where a variable is coming from. I would really like to get the opinions and solutions of other developers here.<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>Dennis<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p>Am Dienstag 03 Februar 2009 16:46:27 schrieb Kristian Lyngstol:<br>
&gt; I've been trying to come up with some good coding standards, but I've<br>
&gt; realized that most of us already know most of this. So instead of trying to<br>
&gt; define every aspect of how we code Compiz-code, I'll try to outline some of<br>
&gt; the finer points. For a more complete list, you can review any of the many<br>
&gt; coding-standard documents out there (For Linux, FreeBSD or any other<br>
&gt; project).<br>
&gt;<br>
&gt; Part of this draft is designed to document the already undocumented code,<br>
&gt; which means some additional work for developers working on existing code.<br>
&gt; I hope the degree of work expected is acceptable.<br>
&gt;<br>
&gt; Note that this is a very rough draft.<br>
&gt;<br>
&gt; 1. Maintainability<br>
&gt;<br>
&gt; Your code will be used by thousands of users, and it will be used even if<br>
&gt; you no longer find yourself working on Compiz. Design your code with this<br>
&gt; in mind. Remember that if you can get 90% of the functionality with 10% of<br>
&gt; the work, that's a good thing.<br>
&gt;<br>
&gt; Split your code into logical pieces. Ideally, functions span 1-3 screens<br>
&gt; on a 80x25 terminal. Complex functions should strive for a smaller size,<br>
&gt; while simple functions (like initialization of large structures) could be<br>
&gt; quite long. If your function is one big if-elseif-elseif-...else-<br>
&gt; statement, each block should be tiny or split out into separate functions.<br>
&gt; Performance-wise, there's nothing stopping you from using an<br>
&gt; inline-function to achieve the same performance with increased readability.<br>
&gt;<br>
&gt; To reduce complexity, clear and well defined interfaces are needed. The<br>
&gt; fewer interfaces we need, the better. This goes for both core&lt;-&gt;plugin<br>
&gt; interaction, and interaction between different parts of core or a plugin.<br>
&gt;<br>
&gt; If you can't avoid complexity, attempt to separate it from the rest of the<br>
&gt; code as much as possible, and make sure it's well-documented in-line in<br>
&gt; your code. Any special exceptions you have to make should be documented in<br>
&gt; the code. Which brings us to...<br>
&gt;<br>
&gt; 2. Document your code<br>
&gt;<br>
&gt; Note that from now on, it is your responsibility to document code you work<br>
&gt; on, even if you aren't the original author. Commits that lack the necessary<br>
&gt; documentation is likely to be revoked. There are exceptions to this, but<br>
&gt; read on.<br>
&gt;<br>
&gt; This does not mean writing on the wiki, writing a seperate text file or<br>
&gt; publishing a book. It means that you stick a little comment in each file<br>
&gt; under the license explaining very briefly what the plugin does, and if<br>
&gt; there are any special tricks used. And it means that if you work on any<br>
&gt; non-trivial function, make sure you stick a comment on top of it explaining<br>
&gt; what it does and how to use it, if it isn't evident.<br>
&gt;<br>
&gt; If in doubt, make a comment.<br>
&gt;<br>
&gt; There's a formula for when to do this, which is loosely based on<br>
&gt; complexity, importance and how exposed your function is. This basically<br>
&gt; means that ANY core function that is not declared static should be<br>
&gt; documented. For core functions, you should also mention where you want this<br>
&gt; function to be used, even if it might already be obvious from header-files.<br>
&gt; This is specially important with functions that are only safe or valid in<br>
&gt; certain contexts.<br>
&gt;<br>
&gt; As for exceptions: If you are only tweaking an existing function, for<br>
&gt; instance to adjust it to an API change, it is not required to comment. If<br>
&gt; you are in doubt about the code functionality, and don't wish to verify<br>
&gt; with others, writing a FIXME: with a brief question/comment so somebody<br>
&gt; else can pick it up, is acceptable.<br>
&gt;<br>
&gt; 3. Be consistent<br>
&gt;<br>
&gt; This applies to both within your own code, but also with regards to the<br>
&gt; rest of the project. Use the same grammatical coding style (found on the<br>
&gt; wiki), similar naming-conventions and so on.<br>
&gt;<br>
&gt; 4. Don't supply useless code or options<br>
&gt;<br>
&gt; Our job as developers is to create mechanism, not policy. Don't use your<br>
&gt; plugin or core-code to change the world. Don't supply 5 different options<br>
&gt; when you can supply one that allows for the same level of flexibility.<br>
&gt; Think about Compiz' position in the bigger picture, not just the world you<br>
&gt; live in.<br>
&gt;<br>
&gt; If you really really really want to change the world, at the very least, do<br>
&gt; it as a warning, not an error!<br>
&gt;<br>
&gt; 5. Expect the unexpected<br>
&gt;<br>
&gt; Check return values. Check input-values for non-static code. It has a<br>
&gt; negative development cost; Any time used now will be made up for down the<br>
&gt; road.<br>
&gt;<br>
&gt; -----------------------------------------<br>
&gt;<br>
&gt; That's it so far. I really hope someone can rip this apart, since I ended<br>
&gt; up trashing my more detailed ideas and threw this together in a hurry. At<br>
&gt; least it should get the discussion started.<br>
&gt;<br>
&gt; Specially since this is written with C, and not C++ in mind.<br>
&gt;<br>
&gt; - Kristian<br>
<p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p><p style="-qt-paragraph-type:empty; margin-top:0px; margin-bottom:0px; margin-left:0px; margin-right:0px; -qt-block-indent:0; text-indent:0px; -qt-user-state:0;"><br></p></body></html>