Pegasus Project Working Paper

Programming Guidelines For the Pegasus Project

Last Update Tuesday, July 24, 2001 08:48 PM

Revision Status

Introduction

This document defines the basic set of guides and rules for programmers contributing to the Pegasus Project

NOTE: This is a draft copy for comment.

RULES and Suggestions - A number of the guidelines below are absolute rules that we must follow in the Pegasus project.  These are the things that will help insure portability and effective interoperability of the components.

Other area are "suggestions" that we strongly suggest be followed so that 1) the code will be readable and usable, 2) we develop a single look to our source code, etc.  In some cases, there may be reasons to bypass some of these suggestiions but we strongly encourage everybody to follow them.  In fact, if there is a real reason we will change to what the group wants and suggestions.

Coding Conventions

1. Indenting Code - Indent by increments of 4 characters (with tabsize of 8).  Use the TAB character.  This is the accepted norm for open source code.
2. Naming Conventions -    ThisIsAClassName - no underscores. thisIsAMethodName() - no underscores. Files Names should take advantage of case and avoid underscores. Files should have the same name as the class (and same case).
   Prepend '_' to private members (including methods).
3. Code Line Length - Lines should not span more than 80 columns. When methods span more than 80 columns, do this:

       void MyClass::myMethod(
                   const char* someReallyLongName,
                   const char* someOtherReallyLongName);
   

4. Use "char* x" rather than "char *x". Either is normally legal for the majority of compilers.
5. Use of const. Use const whenever possible. Use const methods whenever possible.
6. Braces -  Put opening brace on a line by itself. Braces must be aligned with control keyword:

   	for(...)
   	{
           ....
   	}
   

   Not this:

   	for (...)
   	  {
             ....
   	  }

   or this:

   	for (...){
               ....
          }

7. Using Space - No spaces after names.
   Separate functions with blank lines.

       class X
       {
       public:
   	    void f();
   	    void g();
       };

    

8. Not "void f ()" but "void f()".
9. Avoid this:
   callingMyFunction(blah,
          blah2,
          blah3);
   Do this:
   callingMyFunction(
          blah,
          blah2,
          blah3);>/pre>
   

10. Avoid this:
    
    	int        x;
    	float      y;
    

11. Use 0 and not NULL.   
12. Don't separate return type onto its own line: Avoid this:

    	int
    	f()
    	{
            ....
    	}
       

13. Comments - Use /** */ rather than /// for DOC++.
14. Conditional Compilation - Avoid use of conditional compilation for obscuring platrform differences. Use (or put) routines in appropriate platform files or in the System*.cpp files in Common.

Testing

Effective testing is essential to allowing a group to work together in a common code environment. We have created a structure where unit and even system level tests can be created and committed to the source tree as part of all development.  Each major directory section includes a tests subdirectory with individual directories for tests. Please create and commit tests as part of the normal environment wherever it is possible. All core code should include tests created in this manner as well

If you change code to extend it or make corrections, please review the corresponding tests code to 1) add tests to cover the problem corrected 2) extend tests to cover the new code added.

Be mindful that the tests must run on all supported platforms and that a commit may break another platform.

Tests must clean up the effect they have on the repository.

No warnings should be committed. Test big changes on at least Windows and Unix (or Linux)

Committing Code to CVS

Don't commit anything that breaks the build (try a clean slate checkout and build).  Remember that if the build is broken for you, it is also broken for everybody that gets the new code.

Always build and run all regression tests before committing. 

No binaries may be committed to repository. 

There are a few exceptions to this rule but binary files cause problems

Using Outside Code and Libraries

This is an opensource project.  All code that is contributed to this project must be open source and must be made available under the standard license used by the Pegasus project. Do not use any outside libraries that do not meet this criteria.  Further, every reference to outside code make it more complex for others to build and work with the project and introduces potential portability problems.  At the same time, there may be real reasons to use outside code and libraries at times. Thus, for example, the initial project used the ACE_wrappers libraries extensively but with the objective of eventually providing a replacement.  That replacement has been produced, partly because ACE was not available on all of the platforms

Using Make

The Pegasus project has developed a consistent and portable make system that allows bot localized and global builds on a wide variety of systems from Windows to Unix to the tandem platforms today.  This is based on 1) using the GNU Make tool as the core of the make system, 2) minimining the use of other tools.

<<EXPLAIN THE MAKE SYSTEM OR REFERENCE DOC>>>

All code must be reachable (built) from master makefile. Otherwise it will not be reached when doing mass substitutions, testings of builds, and license changes.

DOCUMENTING

<<<THIS SECTION NEED TO BE COMPLETED>>>

Portability Issues

TBD

The Source Tree Structure

We work from a single source tree in CVS.  We have a fixed structure for this structure.

<<<THIS SECTION IS TBD>>>

---END OF DOCUMENT--