Software engineering manual

Martin Beckett - 17 March, 1997

Aims:

This document describes the coding standards and conventions for the camera control system.

This currently applies to the C++ code only, it will be extended to TCL when I write some.

File names

The software is intended to run on Unix and Win32 implementations, both of these platforms have extended filenames of upto 256 characters long with a large number of valid characters. However some tools used on the windows system are based on earlier DOS implementations and are limited to 8.3 characters, ie. 8 characters followed by a full-stop and a further 3 characters. This is also generally true of files stored on CD-ROM. For these reasons the source code files should be kept to 8.3 format if possible.

There are a few differences in the range of valid characters on file names, windows supports slightly more than unix since there are fewer meta-characters for the dos shell. It is recommended that characters in filenames are restricted to a-z 1-9 - _

Some characters are valid but should be avoided, particularly space " (quote) . (dot)

DOS based filesystems use \ as the path separator, unfortunately this is an escape character to strings. All file calls on DOS support the use of the UNIX / separator and this should be used in all hard coded paths or TCL scripts.

Source files

Source code file names should follow the file name convention above. The following extensions are used.

Class names

Class names begin with a Capital letter, the initial letter of each word in the class name is also capitalised, eg Image, TclArg, TclOStream.

Classes which are derived from another class or need another facility to operate should include the name of the requirement, eg TclArg needs tcl.h .

Class functions

Public member functions begin with a lower case letter, with the initial letter of subsequent words capitalised, eg Image.free(), Image.dataSize() .

This can lead to a member function having the same name as a system function performing a similair task. When called as a public member function the class name is attached so there is no ambiguity, when called from inside another member function the local function is used by default, the but the system scope function can be called by putting :: before the function name.

Private member function have the first letter of each word capitalised, this allows a public and private member function to have ( almost ) the same name - not sure if this is a good idea.

Avoid having getXXX() and setXXX() functions to access variables, use operator overloading to have a single function xxxx() with and without arguments.

Class variables

Private variables have lower case first letter with the other words capitalised and a trailing underscore, eg Image.name_, Image.statsValid_ . This allows function to have the same name as a variable. Public variables should be avoided, if they are necessary consider using a private variable and have get/set wrapper functions.

Static data members begin with the word static.

Variables

Variable names in C++ source should use upper case first letter of each word in the variable name.

Hungarian notation

Standard types should use a modified Hungarian notation type which describes theuse of the variable rather than it's machine type. Class data members do not use hungarian notation because the underlying types are likely to change transparently.

Built-in variable types should use the following type specifications.

Typedefs

Integer types should be replaced with typedefs specifying the number of bits.

The main exception to this is local variables used as counters where a signed 16 bit int would be long enough. Assumes that ints are most efficent storage type. Since 32bit implemenation generally packs to 32 bits there is no advantage in using char instead of int to store a small value .

Names of typedefs should be lower case, following system typedefs such as time_t.

Note: bool is now a C++ keyword and the bool typedef has been removed, pixel is still used as a uint16, will be replaced by a class to handle any format pixel


 $Id: softeng.htm,v 1.3 1997/03/18 20:49:58 optics Exp $