Ellemtel C++ Styel and Rules - Source Code in Files

AT&T's Cfront-based compiler creates two functions for every file in order to call constructors and destructors of static objects in the proper order. These functions are named:

• char __sti__file_cc___Fv(); //filename is file.cc
• char __std__file_cc___Fv(); //filename is file.cc

It is easily understood that if a program has two files with the same name but in different subdirectories, there will be name collisions between the functions generated above.

Since class names must generally be unique within a large context, it is appropriate to utilize this characteristic when naming its include file. This convention makes it easy to locate a class definition using a file-based tool. 4.3. Comments

Rule 4

Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents.

Rule 5

All files must include copyright information.

Rule 6

All comments are to be written in English.

Rec. 8

Write some descriptive comments before every function.

Rec. 9

Use // for comments.

It is necessary to document source code. This should be compact and easy to find. By properly choosing names for variables, functions and classes and by properly structuring the code, there is less need for comments within the code.

Note that comments in include files are meant for the users of classes, while comments in implementation files are meant for those who maintain the classes.

All our code must be copyright marked. If the code has been developed over a period of years, each year must be stated.

The standardization of comments makes it possible to automatically generate man-pages from source code. This may be used to keep source code and documentation together until adequate tools for information management are available.

Comments are often said to be either strategic or tactical. A strategic comment describes what a function or section of code is intended to do, and is placed before this code. A tactical comment describes what a single line of code is intended to do, and is placed, if possible, at the end of this line. Unfortunately, too many tactical comments can make code unreadable. For this reason, it is recommended to primarily use strategic comments, unless trying to explain very complicated code.

If the characters // are consistently used for writing comments, then the combination /* */ may be used to make comments out of entire sections of code during the development and debugging phases. C++, however, does not allow comments to be nested using /* */.

Exception to Rule 4

No exceptions.

Exception to Rule 5

No exceptions.

Exception to Rule 6

No exceptions.

   //
   //  File:        test.cc
   //  Description: This is a test program
   //  Rev:         A
   //  Created:     Thur. Oct 31, 1991, 12:30:14
   //  Author:      Erik Nyquist
   //  mail:        [email protected]
   //
   //  Copyright Ellemtel Utvecklings AB 1991
   //  BOX 1505
   //  125 25 ALVSJO
   //  SWEDEN
   //  tel int + 46 8 727 3000
   //
   //  The copyright to the computer program(s) herein
   //  is the property of Ellemtel Utvecklings AB, Sweden.
   //  The program(s) may be used and/or copied only with
   //  the written permission of Ellemtel Utvecklings AB
   //  or in accordance with the terms and conditions
   //  stipulated in the agreement/contract under which
   //  the program(s) have been supplied.
   //

   // THE NEXT TWO LINES ARE STRATEGIC COMMENTS
   // This function does some complicated things. It works like this:
   //  blah-blah-blah ...
   int
   insanelyGreatAndComplicatedFunction( int i )
   {
      int index = i++ + ++i * i-- - --i;  // THIS IS A TACTICAL COMMENT

      return index;
   }

Rule 7

Every include file must contain a mechanism that prevents multiple inclusions of the file.

Rule 8

When the following kinds of definitions are used (in implementation files or in other include files), they must be included as separate include files:

• classes that are used as base classes,
• classes that are used as member variables,
• classes that appear as return types or as argument types in function/member function prototypes.
• function prototypes for functions/member functions used in inline member functions that are defined in the file.

Rule 9

Definitions of classes that are only accessed via pointers (*) or references (&) shall not be included as include files.

Rule 10

Never specify relative UNIX names in #include directives.

Rule 11

Every implementation file is to include the relevant files that contain:

• declarations of types and functions used in the functions that are implemented in the file.
• declarations of variables and member functions used in the functions that are implemented in the file.

Rec. 10

Use the directive #include "filename.hh" for user-prepared include files.

Rec. 11

Use the directive #include <filename.hh> for include files from libraries.

Rec. 12

Every implementation file should declare a local constant string that describes the file so the UNIX command what can be used to obtain information on the file revision.

Rec. 13

Never include other files in an ".icc" file.

The easiest way to avoid multiple includes of files is by using an #ifndef/#define block in the beginning of the file and an #endif at the end of the file.

The number of files included should be minimized. If a file is included in an include file, then every implementation file that includes the second include file must be re-compiled whenever the first file is modified. A simple modification in one include file can make it necessary to re-compile a large number of files.

When only referring to pointers or references to types defined in a file, it is often not necessary to include that file. It may suffice to use a forward declaration to inform the compiler that the class exists. Another alternative is to precede each declaration of a pointer to the class with the keyword class.

True portable code is independent of the underlying operating system. For this reason, relative UNIX search paths should be avoided when including files. The processing of such search paths depends on the compiler and UNIX should not be taken for granted. Instead, search paths should be provided in 'make' files as options for the compiler.

If a file only contains information that is only needed in an implementation file, that file should not be included in another include file. Otherwise, when the information is no longer needed in the implementation file, it may be necessary to re-compile each file that uses the interface defined in the include file.

Every C++ course teaches the difference between the include directives for user-prepared and for library include files. If the file name is bracketed between "<" and ">", the preprocessor will not search for the file in the default directory. This reduces the risk of unintended name collisions between user-prepared and library include files.

By declaring a local constant string, the compiler becomes self-identifying. This may be used to easily determine the version of the program that is used. The string must begin with the characters @(#) to be read by the UNIX what command.

Exception to Rule 7

No exceptions.

Exception to Rule 8

No exceptions.

Exception to Rule 9

No exceptions.

Exception to Rule 10

No exceptions.

Exception to Rule 11

No exceptions.

   #ifndef FOO_HH
   #define FOO_HH

   // The rest of the file

   #endif

   // NOT RECOMMENDED
   #include <../include/fnutt.h>

   // NOT GUARANTEED TO WORK
   #include <sys/socket.h>

   static const char* sccsid =
   "@(#) Exception.cc, rev. A, Copyright Ellemtel Utvecklings AB 1991";

   // file: PackableString.hh
   #ifndef PACKABLESTRING_HH
   #define PACKABLESTRING_HH
   #include "String.hh"
   #include "Packable.hh"

   // It is not necessary to extern-declare class Buffer when
   // each pointer declaration specifies the keyword class as shown below.
   // An explicit extern-declaration makes the code easier to
   // understand.

   extern class Buffer;

   class PackableString : public String, public Packable
   {
      public:
         PackableString( const String& s );
         class Buffer* put( class Buffer* outbuffer );
         // ...
   };

   #endif

   // PackableString.cc

   #include "PackableString.hh"

   // To be able to use Buffer-instances, Buffer.hh MUST be included.

   #include "Buffer.hh"

   Buffer*
   PackableString::put( Buffer* outbuffer )
   {
      // ...
   }