///////////////////////////////////////////////////////////////////////////
// 08. Programming Structure and Style                                   //
//     By: Brent York                                                    //
//         AKA ThaDragon @EFnet's #c                                     //
//         Nuclear Winter Entertainment                                  //
//         Professional Coder for Spheringer Technologies Inc.           //
///////////////////////////////////////////////////////////////////////////


Programming structure and style and why it especially applies to good C..


        This is my second document for the CScene mag, and it applies to
programming structure and style.  Firstly hoever, Id like to draw your
attention to the magazine youre reading this in and to kuru, who
approached me about writing these articles. Thank him, not me ;}.


        Programming structure and style is important in all languages,
but it especially applies to good C and C++.  This is due to C's cryptic
nature.  Its not especially "wordy", and some things in the syntax can be
extremely confusing.  Then to add to the confusing syntax we add alot of
parenthesis and directives, confusing operators, strange function names,
and complex/user defined datatypes.  C introduces alot of new concepts,
and can be very frightening to a new programmer, or even one that has worked
with BASIC.

        
        Despite all this however, programming in C/C++ can be quite
rewarding, and once you get used to it, the syntax is second nature.  The
immense gain from using C and C++ over languages like basic and pascal is
reason enough to leave those languages.

        
        And so structure and style come into the picture.  Alot of
programmers who havent worked with C or C++, and in particular new
programmers are lax on style and structure.  This however, should NOT be
the case, as structure and style are very important to the readability,
and the ability to understand the inner workings of the code.

                
        We have most likely all heard the term "spaghetti code" in our
time, and we understand what it means. Firstly spaghetti code should be
avoided at ALL COSTS...


   *File Description: All About Pasta Code*


   Transcribed from the November-December 1992 issue of the Lawrence
   Livermore National Laboratory Software Engineering Newsletter.

   The mention of ``a feast of spaghetti code'' [``Computer Collectives,''
   CrossTalk, April/May 1992] prompted this response by Raymond J. Rubey
   SofTech, Inc., Fairborn, OH.

   "Nearly every software professional has heard of the term spaghetti code
   as a pejorative description for complicated, difficult-to-understand, and
   impossible-to-maintain, software.  However, many people may not know the
   other two elements of the complete Pasta Theory of Software.

     Lasagna code is used to describe software that has a simple,
   understandable, and layered structure.  Lasagna code, although
   structured, is unfortunately monolithic and not easy to modify.  An
   attempt to change one layer, while conceptually simple, is often
   difficult in actual practice.

     The ideal software structure is one having components that are small
   and loosely coupled; this ideal structure is called ravioli code.  In
   ravioli code, each of the components, or objects, is a package containing
   some meat or other nourishment for the system; any component can be
   modified or replaced without significantly affecting other components.

     We need to go beyond the condemnation of spaghetti code and to the
   active encouragement of ravioli code."




        So obviously, by that document, OOP is the way to go, and IMHO it
is, but thats a totally new document.  Now, we come back to structure,
more importantly, what is it, and how do we implement it?

        
        Simply put, structure is a way of formatting your code such that
it is easy to read, and simple to follow, and pleasing to the eye.
However, there IS a set of rules to follow when making structured code.
They leave quite a bit of leeway, so note that the following point form
rules are my interpretation:


1.) Indent loops, and conditionals.
2.) Comment heavily where things are harder to understand.
3.) Name variables descriptively, but not something extremely large.
4.) Whitespace (tab, enter, space) where necessary to increase readability.
5.) Make functions only have one purpose.
6.) Where possible, split "groups" of functions with the same general purpose
    into thier own seperate source file.
7.) The scope of variables should never exceed that which they are useful
    for. Globals should rarely ever, if ever, be used.
8.) Use "blocking" characters ({,}) only where necessary.
    For Example, consider this if:

        if (blah)
        {
           printf("Blah!\n");
        }

    This blah is much more readable as:

        if (blah) printf("Blah!\n");

    or

        if (blah)
            printf("Blah!\n");

9.) Place a header at the top of the source file, containing a copyright,
    and the following:

    Last modification date/time
    Compiler Developed for
    Platform Developed for
    Description of general purpose of code.

    An example of a header:

    // @(#) Mouse.cc
    // @(#) ~~~~~~~~
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    // @(#) This source is Copyright(c). 1997 by Brent York, All Rights
    // @(#) Reserved. This source is not public domain, and is not shareware.
    // @(#) It is commercial software, and therefore it is illegal to
    // @(#) distribute, and/or modify.
    // @(#) Tue - 8 - Apr 3:10Am - @ - [DJGPP(Devel for GCC/DOS)]
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    //  Comment:
    //
    //    This is the dos djgpp source for controlling the mouse and getting
    //  its status.
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Note that the header is something optional, but it can be quite useful.


        Also, as it applies to header files, encase in an #ifndef,
#define, #endif block to prevent double loading.

Example:

#ifndef __MY_HEADER__
#define __MY_HEADER__



#endif

10.) Comments start at the beginning of the line, or they are indented to the
     same depth when on the same line as code.

     Example:

     // This prints blah
     printf("Blah\n");                          // This prints blah

     // This prints foobar
     printf("This prints foobar\n");            // This prints foobar
                                                // notice these comments are
                                                // all tabbed to the same line?




        Now, comes the concept of style. First off I have one important
thing to say.  PICK A STYLE AND STAY WITH IT.  Theres absolutely nothing
worse than getting a source packet from someone with 6 or 7 different
coding styles used throughout it.  Style is basically where you can
format your code to make it look the way you think looks nice.  It falls
under the leeway that is left by the structuring rules.  Now, note if
used properly style can make for VERY readable code.  Used improperly
it can create havoc.

        
        Now, you ask what style do I use?  First off, the style you use
should be your own, or a modification of someone elses, otherwise youll
never be comfortable.  And seeing as to how style is meant to make you
comfortable with your code, being uncomfortable with your style defeats
the purpose.

        My personal style looks like the following:

Headers:


    // @(#) Mouse.h
    // @(#) ~~~~~~~~~~~~~~~~~~~~
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    // @(#) This source is Copyright(c). 1997 by Brent York, All Rights
    // @(#) Reserved. This source is not public domain, and is not shareware.
    // @(#) It is commercial software, and therefore it is illegal to
    // @(#) distribute, and/or modify.
    // @(#) Tue - 8 - Apr 3:10Am - @ - [DJGPP(Devel for GCC/DOS)]
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    //  Comment:
    //
    //    This is the header definition for mouse.cc
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    #ifndef __MOUSE_H__
    #define __MOUSE_H__

    int mousestatus(int *x, int *y, int *buttons);

    #endif


Code:

        
    // @(#) Mouse.c
    // @(#) ~~~~~~~~~~~~~~~~~~~~
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    // @(#) This source is Copyright(c). 1997 by Brent York, All Rights
    // @(#) Reserved. This source is not public domain, and is not shareware.
    // @(#) It is commercial software, and therefore it is illegal to
    // @(#) distribute, and/or modify.
    // @(#) Tue - 8 - Apr 3:10Am - @ - [DJGPP(Devel for GCC/DOS)]
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    //  Comment:
    //
    //    This is the header definition for mouse.cc
    // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    #include "mouse.hh"

    int mousestatus(int *x, int *y, int *buttons) {
      static int mouse_x, mouse_y, mouse_b;

      asm("movl $3, %%eax
           int $0x33"
          :"=b" (mouse_b), "=dx" (mouse_y), "=cx" (mouse_x)
          :
          :"%eax","%ebx","%ecx","%edx");
      *buttons=mouse_b & 7;
      *x=mouse_x;
      *y=mouse_y;
    }


Note that my { starts on the same line as my function definition, and
that my prototype is in the header file.

Conditionals and loops with my style also follow the same pattern, ie if
it has a block of code assigned to it, the { follows on the same line as
the conditional, or loop.

Other than that, If I define a variable constant, I use const, or
#define... I use macros sparingly but only where needed to increase code
readability.  I use #define to define things like names for video modes
where the names have more meaning.  If I define a variable whos original
state is known, I define that state upon declaration (Ex int i=0;).
And last but not least I use the terse form of operation (i++ z*=12, etc).

        
        This is just my coding style, and as I stated, its best if you
develop your own style, just dont infringe on the structure rules.

        
        So in closing, now that you have a general idea of structure and
style, if you apply it (your way of course), then your code should become
much more readable.  Note that these rules will not become more lax with
different programming models (like oop), they still apply.  Different
coding models support more or less structure depending on the model,
therefore you must make an educated decision on what is correct, and what
isn't.

        
        Above all, keep your code readable.  I hope Ive managed to help
you instead of simply confuse you =}.  Thank you for reading this
document, I hope you enjoyed reading it and got as much out of it as I
did from writing it.


Lastly, Id like to state that the views in here are my own, not Nuclear
Winter Entertainment's, or Spheringer Technologies'.