On Tue, Feb 3, 2009 at 5:44 PM, Dennis Kasprzyk
<onest...@compiz-fusion.org> wrote:
> 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.
>
> DennisI really like the naming conventions here: http://geosoft.no/development/cppstyle.html#Naming%20Conventions Namely: - _ suffix for private member variables. - No prefix/suffix for function parameters or local variables. - :: operator when referring to global variables (which should really be avoided). IMHO, these should make variable scope clear enough while keeping max. readability. What about comments? Should we adopt a doxygen-friendly comment style while we're at it? - Erkin > 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 > > > > _______________________________________________ > compiz mailing list > compiz@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/compiz > > _______________________________________________ compiz mailing list compiz@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/compiz
