Re: [boost] peer review

From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2008-04-29 15:04:36

AMDG

Simonson, Lucanus J wrote:
> According to the submission process I've just reached the refinement
> stage with my GTL library.  Some months back we discussed some of the
> implementation details of my library, including the unorthodox use of
> static cast from the unknown template parameter base type to the GTL
> derived type, which the group concluded was not safe according to the
> standard.
>
> Now that I have *finally* gotten permission to release the library to
> boost I was hoping that we could resume that discussion, come up with a
> workable alternative that satisfies everyone, and I can proceed to
> rewrite the library and "refine" it to the point that it is ready for
> formal review.
>
> I want to rewrite the library so that it will be acceptable for formal
> review.  I was hoping for feedback on what changes you would like to see
> and whether you still believe pursuing eventual review is worthwhile,
> now that you can see the code and we can share specifics of the
> algorithms.  Is everyone particularly busy right now preparing for an
> upcoming release or the boost conference in Aspen?  
>   

Here's my initial reaction from just looking at README.
GTL Programming Conventions section.

2. Camel back capitalization instead of underscores.
Why: This was to be consistent with internal policy and comfort of 
application developers.  Changing it is an option.

3. Class names are capitalized, variable names are not.
Why: Also consistent with the internal policy, it allows the reader to 
easily distinguish between type names and variable names.

This should be changed for consistency with the rest of Boost. 

4. No multiple inclusion protection except on gtl.h. 
Why: The multitude of header files can be included into different 
namespaces within the same application along with different typedef 
declarations for the Unit coordinate data type.  This allows both 32 and 
64 bit instantiation of the same algorithms (through multiple inclusion 
rather than template) and for custom data types that extend the built in 
integer with such things as overflow protection or INF,-INF,NAN special 
values and behaviors.  

I definitely prefer templates.  At the very least, I want versions of 
the individual headers
that are safe to include directly so that I don't have to include all of 
gtl.  The unsafe versions
of the headers should probably go in a separate directory.

8. No abbreviations in function names or class names.

Very strongly agree.

13. Class consistency.  If a class has a member function with a certain 
name, and it makes sense for another class to have a member function 
that could be named the same thing those names should be the same.
Why: More intuitive.  If a rectangle returns its 2d center point with 
the center() function, the rectangular prism should also return its 3d 
center point with a function named center.  That way the learning curve 
is lowered for a developer who is becoming familiar with the API because 
everywhere he expects to find something he finds what he expects.

This important for more than just ease of use.  It is absolutely 
essential for generic code that
needs to process rectangles and rectangular prisms polymorphically.

There are many more code conventions; most of them trivial like what to 
do with whitespace in various circumstances and putting private 
declarations at the end of a class instead of the beginning.

Such internal conventions are your affair as the implementor.  I don't 
really care
as long as the code is not unreadable.

In Christ,
Steven Watanabe