Re: [Freeglut-developer] Style guide?

[Richard R. <sf...@ol...>]

On Mon, Nov 03, 2003 at 08:49:54AM -0600, Fay John F Contr AAC/WMG wrote:
> I think a style guide would be a very good thing.  I can see where I will
> need to change my ways somewhat.  I would suggest that we make a file
> "StyleGuide" in the main "freeglut" directory.  Having it include or refer
> to Chris' EMACS posting would be a good thing; so would an explanation (for
> people like me who don't know EMACS) of what the various things mean.

I could draft a provisional one.  I've been reluctant to push for doing
that, but someone should.  Since I was the one asking for it first, I
thought that I should just sit back and see if anyone felt strongly
enough to take up the gauntlet first.

My thought is to call it "style.c" or "StyleGuide.c" or some such.
It would just be a C source file, filled with comments and examples.
Something like:

/*
 * style.c
 *
 * This is a style guide/example source file for freeglut.
 *
 * General: Code should be ANSI C compliant.  There should be
 * no C++ features.  Machine-specific and OS-specific code
 * should be kept as low as practical, and always protected
 * by #if TARGET_HOST_* lines.  (NOTE: Not #ifdef!)
 *
 * Generally, code in this file demonstrates how freeglut
 * C source files should appear.
 *
 * ...insert more comments here about TABs, indent levels,
 * line-length, ...
 */

/*
 * fgSomeFunc() is a sample internal freeglut function.
 *
 * It is not made static; this allows it to be used by functions
 * in other files of the library.  It is not exported as part of
 * the official freeglut API.  The "fg" prefix indicates an internal
 * freeglut function.
 */
void fgSomeFunc( int init )
{
    int i;

    /*
     * Note the alignment of the {braces}; they match up
     * with the keyword.
     */
    for( i = init; i < MAX_COUNT; ++i )
    {
        /*
         * When there's an "else" part to an "if", we try to
         * arrange it so that the shorter part comes first.
         * This makes it easier to see what the "else" refers
         * to, and aids general quick-scanning comprehension.
         *
         * Where not required, {braces} are omitted.  (freeglut
         * is inconsistant on this point, so this one is more
         * debatable than some other points...)
         */
        if( i % 2 )
            printf( "Odd: %d\n", i );
        else
        {
            printf( "Even: %d\n", i );
            fgSomeFunc( init + 1 );
        }
    }
}


...that's somewhat how I'd start a style guide if I were writing it.
I'd say a bit more in the preamble, but it gives the sense of what
I had in mind when I spoke of a style guide.

Including Chris's EMACS elisp code would be a good thing, too, as
you suggest.  Though since that only helps if you understand EMACS
or have EMACS, I think that ideally the primary style guide should
be descriptive or an example (as above).

Also, the EMACS config snippet doesn't fully solve the style issue,
even if everyone were using EMACS.  (It just helps a lot.  (^&)
The EMACS formatting support is limited more or less to pretty smart
indentation controls.  It doesn't handle spacing around parens, or
other issues.

-- 
  "I probably don't know what I'm talking about."  http://www.olib.org/~rkr/