Martin Beckett - 17 March, 1997
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.
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 code file names should follow the file name convention above. The following extensions are used.
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 .
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.
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.
Variable names in C++ source should use upper case first letter of each word in the variable name.
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.
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 $