[compiz] Coding standard

[Dennis Kasprzyk]

In compiz++ I've made few little changes that do not follow the our previous 
coding style:
- allow variable definition in "for" loops:
for (int i = 0; i < foo; i++)
In the "C" version of compiz we've tried to follow the C89 rules, but this is 
not necessary anymore and should improve readability.
- define variables not at the top of a function:
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.
- indent "case" statements inside of "switch" statements:
in the "C" version of compiz we aligned the case statements at the same level 
like its switch statement:
switch (foo)
{
case foo1:
    break;
case foo2
    break;
}

I think that indenting the "case" statement is a better style here:
switch (foo)
{
    case foo1:
        break;
    case foo2:
        break;
}

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.
I have already two possible solutions here:
Solution 1:
postfix member and global variables with a "_"
prefix function parameter with a "_"

Solution 2:
prefix member variable with "m_"
prefix global variables with "g_"

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.

Dennis

Am Dienstag 03 Februar 2009 16:46:27 schrieb Kristian Lyngstol:
> I've been trying to come up with some good coding standards, but I've
> realized that most of us already know most of this. So instead of trying to
> define every aspect of how we code Compiz-code, I'll try to outline some of
> the finer points. For a more complete list, you can review any of the many
> coding-standard documents out there (For Linux, FreeBSD or any other
> project).
>
> Part of this draft is designed to document the already undocumented code,
> which means some additional work for developers working on existing code.
> I hope the degree of work expected is acceptable.
>
> Note that this is a very rough draft.
>
> 1. Maintainability
>
> Your code will be used by thousands of users, and it will be used even if
> you no longer find yourself working on Compiz. Design your code with this
> in mind. Remember that if you can get 90% of the functionality with 10% of
> the work, that's a good thing.
>
> Split your code into logical pieces. Ideally, functions span 1-3 screens
> on a 80x25 terminal. Complex functions should strive for a smaller size,
> while simple functions (like initialization of large structures) could be
> quite long. If your function is one big if-elseif-elseif-...else-
> statement, each block should be tiny or split out into separate functions.
> Performance-wise, there's nothing stopping you from using an
> inline-function to achieve the same performance with increased readability.
>
> To reduce complexity, clear and well defined interfaces are needed. The
> fewer interfaces we need, the better. This goes for both core<->plugin
> interaction, and interaction between different parts of core or a plugin.
>
> If you can't avoid complexity, attempt to separate it from the rest of the
> code as much as possible, and make sure it's well-documented in-line in
> your code. Any special exceptions you have to make should be documented in
> the code. Which brings us to...
>
> 2. Document your code
>
> Note that from now on, it is your responsibility to document code you work
> on, even if you aren't the original author. Commits that lack the necessary
> documentation is likely to be revoked. There are exceptions to this, but
> read on.
>
> This does not mean writing on the wiki, writing a seperate text file or
> publishing a book. It means that you stick a little comment in each file
> under the license explaining very briefly what the plugin does, and if
> there are any special tricks used. And it means that if you work on any
> non-trivial function, make sure you stick a comment on top of it explaining
> what it does and how to use it, if it isn't evident.
>
> If in doubt, make a comment.
>
> There's a formula for when to do this, which is loosely based on
> complexity, importance and how exposed your function is. This basically
> means that ANY core function that is not declared static should be
> documented. For core functions, you should also mention where you want this
> function to be used, even if it might already be obvious from header-files.
> This is specially important with functions that are only safe or valid in
> certain contexts.
>
> As for exceptions: If you are only tweaking an existing function, for
> instance to adjust it to an API change, it is not required to comment. If
> you are in doubt about the code functionality, and don't wish to verify
> with others, writing a FIXME: with a brief question/comment so somebody
> else can pick it up, is acceptable.
>
> 3. Be consistent
>
> This applies to both within your own code, but also with regards to the
> rest of the project. Use the same grammatical coding style (found on the
> wiki), similar naming-conventions and so on.
>
> 4. Don't supply useless code or options
>
> Our job as developers is to create mechanism, not policy. Don't use your
> plugin or core-code to change the world. Don't supply 5 different options
> when you can supply one that allows for the same level of flexibility.
> Think about Compiz' position in the bigger picture, not just the world you
> live in.
>
> If you really really really want to change the world, at the very least, do
> it as a warning, not an error!
>
> 5. Expect the unexpected
>
> Check return values. Check input-values for non-static code. It has a
> negative development cost; Any time used now will be made up for down the
> road.
>
> -----------------------------------------
>
> That's it so far. I really hope someone can rip this apart, since I ended
> up trashing my more detailed ideas and threw this together in a hurry. At
> least it should get the discussion started.
>
> Specially since this is written with C, and not C++ in mind.
>
> - Kristian


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freedesktop.org/archives/compiz/attachments/20090204/519b2c87/attachment.html