Re: [Groff] Overview, Sept. 2014

[Ulrich Lauther]

On Thu, Sep 11, 2014 at 01:11:40PM -0400, James K. Lowden wrote:
> 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!  
> 
As I understand it, the man-pages are directed at the user of a program
who wants to know WHAT a program is supposed to do and how she can control
it via options.

Comments in the source are directed at the programmer, who wants to understand
HOW the functionality of the program is accomplished.

I think, these are two totally different cups of tea.

I am not a friend of overloading code with comments, like
        a++; // a is incremented
but I doubt that a sophisticated mathematical algorithm, e.g., Knuth/Plass's
dynamic programming approach to paragraph formatting could be understood
without some helpful comments, including
        - the task a class is supposed to do or the role these object(s) play
        - the role of key variables
        - pseudo code of non-trivial algorithms
        - pointers to relevant literature
All this is not to be found in the man-page and does not belong there.

        ulrich