Source Files


File Names

[sf01] Source files should be named using the same capitalization rules used elsewhere in A&L source code. Source files containing the implementation or interface of a class should always have the same name as the class (dropping the leading A prefix ( see Reserved Prefixes_) when present).

For example, the header file for the C++ class AHyperlink would be Hyperlink.h, and the implementation file would be named Hyperlink.cpp.

Source files that do not contain a single class should use a descriptive name that clearly identifies the contents of the file.

Copyright Notice

[sf02] Every source file should begin with a single line indicating the copyright claimed for that file. Our standard contract lets A&L retain copyright on code that is not specific to a project. Any other code should claim a copyright on behalf of the client.

For example, code to read and parse a generic tab-delimited file should retain the A&L copyright. Code to read and parse a data file using a client's proprietary format should use the client's copyright.

All source files that are copyright A&L should include the following text in a comment as close to the top of the file as possible (where possible, this should be the very first line in each file):

   // Copyright (c) <<current year>> Art & Logic, Inc. All Rights Reserved.

The project manager can provide the exact text to use for the client's copyright statement.

Subversion Id Tag

NOTE: Since git has no functionality that corresponds to this CVS/SVN feature, modern projects stored in git should disregard this 'Id Tag' section of the Style Guide.

[sf03] Immediately after the copyright notice, each source file should include this line, also inside a comment::

   // $Id$

When the source file is checked into our source code management system, it will be expanded into the current file revision level and date/time of last check in, like::

   // $Id: SomeFile.java 130 2003-04-16 20:17:20Z jcoder $

[sf04] If source will eventually be made visible to end users (for example, HTML files or configuration files that are included with end-user deliverables, the project manager may instead opt to use the Revision and Date Subversion keywords (there is no Subversion keyword for the file name), to omit the identification of the last developer to check the file in, like::

   // $Revision$ $Date$

Including Other Files

[sf05] When including or importing other source files, modules, or packages into a source file, the statements that perform that inclusion should be grouped together at the top of the source file, as follows:

  • system-defined files, sorted alphabetically
  • at least one blank line
  • project-specific files, sorted alphabetically

For example, on a C++ project you might see a file that contains:

   #include <fstream>
   #include <iomanip>
   #include <ios>
   #include <sstream>
   #include <time.h>

   #include "ColorDoc.h"
   #include "DrawingView.h"
   #include "Error.h"
   #include "UndoRedo.h"

In Java, you might see something like::

   import java.io.*
   import java.util.*

   import com.ArtLogic.util.*
   import com.ClientName.*

[sf06] There are two obvious exceptions to this layout:

  • Compilers that support pre-compiled headers often require that the pre-compiled header file be listed first
  • To detect and prevent unintended couplings between header files, you are encouraged (but not required) in a .c or .cpp file to include that file's header file first, like:

    • #include¬†"ThisFile.h"

    • blank line
    • #include system headers

    • blank line
    • #include project files

File Cohesion

[sf07] Prefer to always have a single class per source file. An obvious exception to this is when developing exception classes that are tightly coupled to a specific class (in effect, becoming part of its interface). It may also make sense to group together a collection of small utility classes into a single source file.