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
pgpg59X8W2y2p.pgp
Description: PGP signature
_______________________________________________ compiz mailing list compiz@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/compiz
