[Bf-committers] Coding style

[Chris Burt]

For further information on the topic of coding style please read: 
http://www.blender3d.org/cms/Coding_Style.141.0.html

Logic would say that whatever Ton has pointed out here takes precedence 
over the document linked above because the information is newer. If 
there are in fact differences and an experienced coder has time, it 
would be nice to see these changes incorporated into the Coding Style 
document. This set of docs is VERY USEFUL to beginners (and some 
experts) and in my opinion can probably eliminate some of the hassle 
involved with reviewing patches. Especially if the authors of said 
patches are encouraged to read this guide carefully first.

If anyone is willing to volunteer some time to update this, please let 
me know or share your comments with me via this mailing list, IRC, or 
e-mail. I would be glad to help anyone who does not have publishing 
rights to get their changes to the compiling document reviewed and 
published as soon as the work is done. If no such volunteer makes 
him/herself known I'll do my best to keep the issue alive and, if 
possible, make the changes myself when I have the time (and the 
knowledge) to do so accurately, though it is my believe that some of 
this information is covered already (I'd have to check to be sure and as 
of this moment I haven't read the document for a while.)

If you have any objects/suggestions/insults/threats/etc, please let me 
know. Thanks!

Regards,
--Chris

Ton Roosendaal wrote:
> Hi,
> 
> I've reviewed transform code, and a couple of nice style improvements  
> were accepted by Martin. Thought it would be nice to mention it to list  
> here as well. Below applies for most code in source/blender/, apart  
> from c++ or python;
> 
> -> function naming
> 
> It helps to have a visual clue wich calls are:
> - part of the exported API (for rest of Blender)
> - part of the 'module' (like only for all transform files).
> - entirely local (to the C function)
> 
> For Blender API functions there exist two mixed conventions now, one is  
> the OpenGL style;
> 
> void glSwapBuffers()
> void uiDefButton()
> 
> or as added in NaN days:
> 
> BIF_ThemeColor()
> BKE_read_file()
> 
> Note that in both cases names include upper cases.
> Local calls or module-only calls use lower-case, like
> 
> void ui_def_button()
> 
> and have a static declaration when strictly defined to be local to C  
> function.
> 
> static void ui_def_button()
> 
> -> variable naming
> 
> Only use capitals in variable names to warn they're globals.
> I also really like to see variable declarations grouped per equal  
> types, and in descending size. So first structs, then floats, ints,  
> shorts and ending with chars. Static or externs are on top. That's  
> personaly maybe, but helps reading code :)
> 
> -> defines
> 
> Allmost all defines added since 5 years ago (when more people started  
> coding blender :) have an indication which group/module/lib they belong  
> to. This *especially* when exported as part of the API. Defines like  
> "TRANSLATION" etc are confusing... you can do that for module-only (or  
> local defines) but not for the exported ones.
> 
> Example: TRANS_xxx or TFM_xxx etc.
> 
> -> include files
> 
> Like for function names, the include files also separate in a global  
> version (like BIF_interface.h) and a local version (interface.h), with  
> the latter only being allowed to include for the interfacexxx.c  
> function themselves.
> 
> Giving each C file its own header is in such a structure not needed,  
> but can be used optionally... again, only for local exports to the  
> 'module' itself.
> 
> Right now, all source/blender/src/ code has the include files in  
> source/blender/include. As already proposed ages ago, this src/  
> directory could be modulified once. :)
> 
> -> use TABs!
> 
> Check on your editor setting!
> 
> -Ton-
> 
> ------------------------------------------------------------------------ --
> Ton Roosendaal  Blender Foundation ton at blender.org  http://www.blender.org
> 
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at projects.blender.org
> http://projects.blender.org/mailman/listinfo/bf-committers
> 
>