Programming styles: Feedback

[Gilbert Peffer]

Hi there,
I have read through the C++ Programming Style Guidelines, and thought that,
with a few exceptions (in addition to those posted by Luigi yesterday), all
the rules were acceptable. The ones where I have some comments are:

22. I often call variable or object containers <set>, although for a
mathematical purist, this can provoke considerable grief

24. I usually use <num>, but <no> is as good. One may as well permit both

36. This is currently in contradiction to some of the code in Quantlib. I
myself are not too consistent in this particular style case. What do you
think?

38. ...TABs should be avoided. Does anybody have an idea of the real impact
the use of TABs can have?

69. I prefer 4 spaces

73. I prefer the SUN recommendation, but this has no big impact anyway, I
think

87. I would like to add a suggestion for function/subroutine definitions.
For long argument lists (and for short ones as well), I prefer to stack the
arguments

    runThisRoutine (int     numNodes,             // Number of nodes
                    int     numElements,          // Number of elements
                    double* coordinateSet,        // Nodal coordinates
                    int*    connectivityList) {   // Elements connectivites
        blah blah
    }

so one can comment each of the arguments individually. Unless somebody has a
strong objection about this (I guess it is a style choice one has to get
used to) I wouldn't mind seeing it implemented in Quantlib

That's about it. Please send me your suggestions so I can put a draft
together

Best regards

Gilbert

[Luigi Ballabio-3]

Hi all,

At 11:58 AM 12/20/00 +0100, Gilbert Peffer wrote:
>36. This is currently in contradiction to some of the code in Quantlib. I
>myself are not too consistent in this particular style case. What do you
>think?

I'm not that consistent myself - mostly out of laziness. But we can move
the body of the methods outside the class definition. Of course they will
stay in the header file for them to be inlined. One forced exception are
template methods of a non-template class, which VC++ won't compile unless
they are declared inside the class.

An additional thought: not cluttering the header with such inlined bodies
is somehow less of an issue, as the Doxygen-generated documentation for the
class has a clearer layout than the header file itself...

>38. ...TABs should be avoided. Does anybody have an idea of the real impact
>the use of TABs can have?

Actually I though that inserting real tab characters instead of spaces
allowed people to set the indentation to the number they like without
conflicting with others... am I missing something obvious here?

>87. I would like to add a suggestion for function/subroutine definitions.
>For long argument lists (and for short ones as well), I prefer to stack the
>arguments
>
>     runThisRoutine (int     numNodes,             // Number of nodes
>                     int     numElements,          // Number of elements
>                     double* coordinateSet,        // Nodal coordinates
>                     int*    connectivityList) {   // Elements connectivites
>         blah blah
>     }
>
>so one can comment each of the arguments individually. Unless somebody has a
>strong objection about this (I guess it is a style choice one has to get
>used to) I wouldn't mind seeing it implemented in Quantlib

We might be forced to follow the Doxygen requirements here, if we want such
comments to be extracted and put into the documentation. The Doxygen
comment block would look like:

     /*! \brief short description of the method
         \param numNodes         number of nodes
         \param numElements      number of elements
         \param coordinateSet    nodal coordinates
         \param connectivityList elements connectivities
         \return description of the returned value
     */
    double runThisRoutine (int numNodes, int numElements,
                            double* coordinateSet, int* connectivityList) {
         blah blah
     }

Bye,
         Luigi

[Ferdinando M. Ametrano-2]

Hi all

Gilbert wrote:
 > Please send me your suggestions so I can put a
 > draft together
my 0.2$ on programming styles

92. Replace Doc++ with Doxygen

>>87. I prefer to stack the arguments
>>
>>     runThisRoutine (int     numNodes,             // Number of nodes
>>                     int*    connectivityList) {   // Elements connectivites
>>         blah blah
>>     }
>>
>>so one can comment each of the arguments individually.
>We might be forced to follow the Doxygen requirements here, if we want
>such comments to be extracted and put into the documentation. The Doxygen
>comment block would look like:
>
>     /*! \brief short description of the method
>         \param numNodes         number of nodes
>         \param connectivityList elements connectivities
>         \return description of the returned value
>     */

I would follow Doxygen requirements. Then argument stacking is probably
redundant, but it doesn't hurt

 > 90) We'll have to stick to /* ... */ when comments
 > are to be extracted by Doxygen.
Doxygen rules.


 > 17) ok for employee.setName(). However, employee.getName() seems a
 > bit redundant to me - employee.name() is just as clear.
 > Unfortunately this would conflict with 6) since name() is not a
 > verb (well, not in this case).
I prefer the set/get symmetry. This do not conflict with 6 ;-)

>>38. ...TABs should be avoided.
>Actually I though that inserting real tab characters instead of spaces
>allowed people to set the indentation to the number they like without
>conflicting with others... am I missing something obvious here?
The 80 column limit cannot allow for different TABs.
I would join Luigi and Gilbert in the "4 spaces" club


I agree on all the following statement:

 > 5) I'd prefer enumerations inside classes and static const class
 > variables in mixed case starting with lower case.

 > 24. I usually use <num>, but <no> is as good. One may as well permit both

>36. [...] we can move the body of the methods outside the class
>definition. Of course they will stay in the header file for them to be
>inlined. One forced exception are template methods of a non-template
>class, which VC++ won't compile unless they are declared inside the class.

 > 49) I would make an exception for static const variables,
 > for which I see no reason for access through a get() method.

 > 70) I like better example 1 for classes and functions too.

 > 73. I prefer the SUN recommendation, but this has no big impact
 > anyway, I think

 > 83) f (x) looks very strange to me with the space in the middle.


ciao -- Nando