[vtk-developers] vtk Coding style : Proposed change

John Biddiscombe biddisco at cscs.ch
Mon Mar 27 10:51:25 EST 2006 

David
> 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)
indeed. In fact I nicked that function from CMake and was hoping it 
would be added to SystemTools, but I should indeed prefix it with something.
> 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.
I usually stick to this system, but maybe missed a few. I'm happy to fix 
these.
> 3) Consistent use of lower case for first character of parameter and 
> local variable names, consistent use of upper case for ivars and methods.
Again, I'd be happy to fix this.
> 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.
I'm not all that happy about this, but if I can keep my indentation, I'm 
willing to compromise on comment truncation. I often allow lines to go 
much longer as I have a big screen and don't mind them long. Why 78? why 
not 88 or better still 98? My screen is normal sized, but even with my 
failing eyesigh I can see about 100 chars across a window.

> 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.
This is the main issue for me. Indentation. (And line length!)
>
> 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).

OK. I'm prepared to reword it and reduce the scope to indentation, scope 
of brackets etc, but I'd like more than 78 chars across the screen. Give 
me a concrete reason to limit to 78. does vi only handle this many. I 
don't believe it! Do you mean only comments, or long if statements too?

> Also, it is always a bad, bad thing to presume that you are the only 
> person who is going to be maintaining your code.
Of course what you say is true. But it is also true that the vast 
majority of debugging/editing/patching goes on by a very small subset of 
people for any given class. unless kitware reworks the pipeline or 
scalars again, there's little reason for anyone other than me and the 
small number of netCDF users who are ever likely to debug this 
particular class to get involved with it.

JB


>
> - 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
>>   
>


-- 
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

More information about the vtk-developers mailing list