[compiz] Coding standard

[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 --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/compiz/attachments/20090203/78319cbd/attachment.pgp