[vtk-developers] vtk Coding style : Proposed change

David Gobbi dgobbi at atamai.com
Mon Mar 27 10:04:36 EST 2006 

Hi John,

I looked at your vtkNetCDFReader to see exactly how different the code 
style is from VTK, and I would have to say that it is more similar than 
it is different. Personally, I'm fine with a little flexibility in style 
and would really like to see this class become part of VTK. There are 
some things that would need to change, though:

1) You don't prefix your functions with "vtk", which is going to lead to 
name collisions when you define functions like this:

bool Split(const char* str, vtkstd::vector<vtkstd::string>& lines, char 
separator)

On many UNIX system, if the reader is linked with any module that 
contains a "Split" method with a similar signature, the program will 
fail. This is particularly pernicious for run-time linking, since the 
failure may work on some machines but not others, depending on whether a 
"Split" function exists in the myriad system and GUI libraries.

2) Use of "this->" in front of ivars: yes, it's verbose, but it avoids 
confusion and helps me visually parse the code a lot faster.

3) Consistent use of lower case for first character of parameter and 
local variable names, consistent use of upper case for ivars and methods.

4) Comment lines should be consistently 78 chars or less for us people 
who use emacs and vi (there's a lot of us!). This sort of a thing I'd be 
glad to fix after you committed the code, though, since it is really a 
change for the sake of myself and my ilk.


Those are the things that are important to me, but of course it is 
Kitware that has the final say. As for indentation of braces and blocks, 
I think that what you do is fine and would like to see the Kitware 
guidelines open up in that regard, and only require that all blocks have 
braces while allowing some flexibility in indentation.

I certainly don't agree with your two proposed additions to the VTK 
style guide, though: they are far too broad. Kitware's code "policy" 
exists for a reason, and it's not just to ensure consistency: it's also 
to avoid some common errors (like #1 above).

Also, it is always a bad, bad thing to presume that you are the only 
person who is going to be maintaining your code.

- David


John Biddiscombe wrote:
> Andrew
>>
>> John, I don’t like the idea.
>>
> Well that's not good enough (for me). I don't like many things, but 
> they are not policy because of it.(eg having all the parametric 
> sources in Common strikes me as wrong, but they are still there).
>>
>> I realize it is an effort to convert to the VTK coding style, but I 
>> think that coding styles should be consistent throughout a library. 
>> Otherwise it gets difficult to read code as you constantly have to 
>> switch styles. It also increases the possibility of missing subtle 
>> errors.
>>
> I disagree. I have worked with C/C++ for many years and so have all 
> the vtk developers. They can cope with different styles (and so can I, 
> but I'd rather work with mine). I am only asking for the right to 
> contribute complete modules in my style. I will not alter any existing 
> classes to a new style.
>>
>>
>> Surely it is not that much effort to fit in with the VTK style. With 
>> modern text editors it should be simple to reformat. I think someone 
>> at VTK has some scripts for this … but I may be wrong. I know there 
>> is an EMACS thingie for VTK formatting floating around somewhere.
>>
> It's not about difficulty in converting the code. Its about 
> maintenance. I will be able to debug faster if the code is in my 
> format. I have had a lot of emails about the netCDF reader and none of 
> them complained about the coding style. The Style is really not that 
> important to most people.
>>
>> I don’t use their style either and for the vtkParametric functions I 
>> had to convert to their style. It took a bit of time but it also had 
>> the advantage that when doing it I had to read the code and fixed up 
>> a few oddities etc. in the code
>>
> I have looked at every single cvs log message for all the Parametric 
> sources. Apart from
> 1) Moving to common by Will
> 2) A style change by Matthieu (capitalization)
> there is only one commit by anyone other than you (it was Will) which 
> contained a substantial change to the code - and in that case it was a 
> change of base class on (I think) one file.
>
> You are the only one who maintains these classes - and I will probably 
> be the one who maintains my classes. I would like to work with my code 
> not a version of my code that has been mangled up. It will make no 
> difference to anybody at all if I use my style on my classes, and 
> therefore it is not worth enforcing it. The bad side is that I'll just 
> continue doing what I'm doing now and not contribute anything new 
> because I feel very strongly about it and I would rather keep the code 
> the way I like it.
>
> JB
>>
>> Regards
>>
>> Andrew
>>
>> ------------------------------------------------------------------------
>>
>> *From:* vtk-developers-bounces+andrew.amaclean=gmail.com at vtk.org 
>> [mailto:vtk-developers-bounces+andrew.amaclean=gmail.com at vtk.org] *On 
>> Behalf Of *John Biddiscombe
>> *Sent:* Sunday, 26 March 2006 05:37
>> *To:* vtk-developers
>> *Subject:* [vtk-developers] vtk Coding style : Proposed change
>>
>> Dear vtk developers,
>>
>> I have a number of modules that I would like to (and have been asked 
>> to) contribute in the near to mid-term future but I do not wish to 
>> reformat my code to fit the vtk coding style. If (for example) 
>> vtkNetCDFReader is contributed to vtk/paraview, I will most likely be 
>> doing the majority of maintenance and fixing work on the class(es). I 
>> do not like the vtk coding style as I find it hard to quickly 
>> mentally parse (bracket indentation in particular) and I would like 
>> to reserve the right to use my own coding style on the contributed 
>> class(es). I can digest and debug my own code considerably faster 
>> because I am familiar with the way it is structured and laid out.
>>
>> I would like therefore to propose that the vtk coding style (as 
>> described here http://www.vtk.org/Wiki/VTK_Coding_Standards ) be 
>> modified to include the following (additional text in red - apologies 
>> for non html capable email readers)
>>
>>     * The indentation style can be characterized as the "indented
>>       brace" style. Indentations are two spaces, and the curly brace
>>       (scope delimiter) is placed on the following line and indented
>>       along with the code (i.e., the curly brace lines up with the
>>       code). Example:
>>
>>         [example deleted]
>>
>>     * Code contributions/modifications should use the accepted vtk
>>       coding style as outlined in this document, with the exception
>>       that contributions which consist of new modules in their
>>       entirety are permitted to use their own style - provided the
>>       style is consistent throughout the whole contributed module.
>>     * Modifications to existing code must follow the coding style of
>>       the module being changed. If the code being changed is a
>>       contributed module which deviates from the accepted vtk style
>>       then the changes should attempt to follow the contributed style.
>>
>> To summarize my changes in a nutshell :
>> Any fixes/modifications/additions to existing code must follow the 
>> coding style of the module being modified : In the vast majority of 
>> cases this means that the standard vtk coding style must be used. All 
>> existing classes must continue to use the vtk coding style. But I 
>> (for one) would like to be able to contribute new code in my own 
>> style and anyone modifying the code I have contributed should follow 
>> the style I have used in the module as best they can.
>>
>> If this proposal is accepted, then I will be happy and will 
>> (hopefully) never need to raise the issue of coding style again. I 
>> have asked in the past to change the style, but met with opposition, 
>> I believe the wording of my proposition above is flexible enough to 
>> satisfy myself and others without opening the doors to complete 
>> corruption of the existing code-base. Please feel free to propose 
>> further changes to my text, but do not dismiss out of hand my 
>> proposition as I believe that the majority of vtk developers are 
>> capable of coping with different styles providing they are 
>> consistent. In general very few vtk users (or indeed developers) 
>> study the source code in great depth for modules other that those 
>> that they are making use of heavily, (and have problems with). I find 
>> it acutely painful to reformat code that may be thousands of lines 
>> long into a style that I don't like, for nobody's benefit.
>>
>> NB : One possible addition to my proposal might be that modules 
>> deviating from the standard vtk style should contain a disclaimer
>> "This class uses a different coding style to the vtk standard, please 
>> pay careful attention to code layout when debugging"
>>
>> yours
>>
>> JB
>>
>> -- 
>> John Biddiscombe,                            email:biddisco @ cscs.ch
>> http://www.cscs.ch/about/BJohn.php
>> CSCS, Swiss National Supercomputing Centre  | Tel:  +41 (91) 610.82.07
>> Via Cantonale, 6928 Manno, Switzerland      | Fax:  +41 (91) 610.82.82
>
>
> -- 
> John Biddiscombe,                            email:biddisco @ cscs.ch
> http://www.cscs.ch/about/BJohn.php
> CSCS, Swiss National Supercomputing Centre  | Tel:  +41 (91) 610.82.07
> Via Cantonale, 6928 Manno, Switzerland      | Fax:  +41 (91) 610.82.82
>   
> ------------------------------------------------------------------------
>
> _______________________________________________
> vtk-developers mailing list
> vtk-developers at vtk.org
> http://www.vtk.org/mailman/listinfo/vtk-developers
>

More information about the vtk-developers mailing list