Re: [Groff] Overview, Sept. 2014

[James K. Lowden]

On Wed, 10 Sep 2014 11:49:37 +0200
Ulrich Lauther <address@hidden> wrote:

> other modifications would really
> improve readability and maintainability:
>         - capitalization of class names
>         - a naming convention for class member variables
>         - reducing the number of global variables

You want to tread lightly where style is concerned.  Whether or not
something is more "readable" depends very much on what you're used to.
There's no consensus in the C ++ community at large on the above
recommendations.  

Many people are accustomed to capitalizing classes and decorating
member names.  I think the first is a requirement in Java, and the
latter was popularized by Microsoft's ugly "m_varname" convention.   In
his books, Stroustrup uses capitalized class names and ordinary,
undecorated variable names.  

Stroustrup has observed that if you ask a room of experts for
suggestions on how to improve C++ and make it more accessible to the
beginner, you'll be deafened by silence.  If you want a lively
discussion, he says, ask where the curly braces should go.  

>         - for each class a block of comments explaining what the
> class is all about

For this particular suggestion to appear on the groff list is a little
ironic, no? Since the epoch Unix source code has been documented with
man pages adjacent to the source in the tree, with its rich formatting
features. Surely in-line text-only documentation as comments would be a
retrograde step, and a long one at that?  Else we might as well close
up shop and rename the project Doxygen!  

--jkl