Sensormatic Engineering Standard Practice

Title

High-Level Language Coding/Documentation Standard

No. Issue Date Supersedes

ESP-30

September 28, 2007

April 16, 1993

Table of Contents
1.0 2.0 3.0 4.0 Scope..................................................................................................................................2 Purpose..............................................................................................................................2 Justification .......................................................................................................................2 General Standards ............................................................................................................2 4.1 Copyright Block ......................................................................................................2 4.2 Identifiers................................................................................................................2 4.3 White Space...........................................................................................................3 4.4 Class Header .........................................................................................................3 4.5 Function Header.....................................................................................................3 4.6 Deviation from Standard ........................................................................................3 Additional Standards for C and C++ ...............................................................................4 5.1 Comments..............................................................................................................4 5.2 Function Description Block ....................................................................................4 5.3 File Layouts............................................................................................................4 5.4 Identifiers................................................................................................................4 5.5 Literals....................................................................................................................5 5.6 Pointer Operator.....................................................................................................5 5.7 Brackets .................................................................................................................5 5.8 Include Files ...........................................................................................................5 5.9 Namespaces ..........................................................................................................5 5.10 Library or Component Files....................................................................................5 5.11 File Naming ............................................................................................................5 5.12 Header Files...........................................................................................................5 5.13 Keyword/Data Type Naming ..................................................................................6 5.14 Global Variable Declarations .................................................................................6 5.15 Function Declarations ............................................................................................6 5.16 Formatting If Statements ......................................................................................6 5.17 Formatting Loops ...................................................................................................7 5.18 Formatting Switch Statements ...............................................................................7 5.19 Code Organization .................................................................................................7 5.19.1Modules........................................................................................................7 5.19.2Functions......................................................................................................7 Additional Standards for C# ............................................................................................8 6.1 Comments..............................................................................................................8 6.2 Class Header .........................................................................................................8 6.3 Function Header.....................................................................................................8 6.4 Source File Layout .................................................................................................8 6.4.1Naming Conventions......................................................................................9 6.5 Literals....................................................................................................................9 6.6 Statement Formatting.............................................................................................9 6.7 File Naming Conventions.....................................................................................10 6.8 Namespaces ........................................................................................................10

5.0

6.0

ESP-30

Confidential

Page 1 of 10

1.0

Scope

This standard applies to all system software developed by or for the EAS SBU.

2.0

Purpose

This standard is intended to promote 1) uniform high-level language (HLL) software documentation and 2) maintainability in system-level software generated by the development teams. It defines software source file organization and naming conventions designed to ensure uniform appearance and understandability across product lines. The General Guidelines given in section 4.0 should be applicable to most high level language environments. Specific guidelines for the languages currently in use in development are provided in the subsequent sections. Enforcement of the standard will be part of the Formal Inspection/Code Walk-Through process.

3.0

Justification

The need exists to produce high-level language software that is easily understood, consistentlystructured, reproducible, and easily modified. The principal expense item in any major software project is maintenance cost. Uniform coding standards reduce retraining time and, implicitly, maintenance costs.

4.0
4.1

General Standards
Copyright Block
All source files will include the following standard copyright block:

*********************************************************************************** Tyco Safety Products COPYRIGHT DECLARATION: (current year) Sensormatic Electronics Corporation No part of this computer software may be printed or reproduced or utilized in any form by any electronic, mechanical or other means now known or hereafter invented, including photocopying and recording, or in any information storage and retrieval system, without the express written permission of Sensormatic Electronics Corporation. ***********************************************************************************

This block is a comment and will be proceeded by, or enclosed in, the appropriate syntactic structure for comments in the given language. For example in C/C++ each line will be proceeded by //.

4.2

Identifiers
Camel Case should be used for all identifiers except as noted elsewhere in this document. Camel Case form consists of the following: o o o The identifier contains a series of one or more words concatenated together. The identifier starts with a lowercase character. The separation of words in the identifier is indicated through the capitalization of the first letter in each subsequent word in the identifier (example: officePrinter).

Even a short-lived variable that may appear in only a few lines of code must still be given a meaningful identifier.

ESP-30

Confidential

Page 2 of 10

The use of single-letter identifiers, such as i or j, is reserved for short-lived loop index variables. Overly abbreviated words can make identifiers unclear. Words within an identifier can be abbreviated but each word in the identifier must be clear and obvious. Hungarian Notation, where the type of variable is used as a prefix for variable identifiers (example. ptrOfficePrinter) should NOT be used. If necessary for clarity the type of the variable can be included at the end of the identifier for the variable (example: officePrinterPtr). Boolean variable identifiers will start with the word is or has in order to indicate yes/no, true/false relationship (example: isNewPage). Function, procedure or method name identifiers will start with a capital letter (example: StartPrinting()). If the language used supports the concepts of classes or structures, then member variable identifiers will begin with an m_ with the balance of the identifier being in camel case (example: m_timeToWait). Identifiers for constants will start with a capital letter with the balance of the variable name following the general rule for the separation of words (example: DaysInWeek).

4.3

White Space

White space (characters such as space, tab, and new lines) should be used to provide organizational clues to the structure of the source code. Use blank lines to separate code into logically related groups within a function, procedure or method. Use indentation to provide visual clues to the scope of a given section of code. Tab characters should be used for indentation rather than space characters. Separate operators (e.g. =, ==, !=, +, -, /, <, >, <=, >= etc.) from other symbols by a space. Separate function, procedure or method arguments from each other with a white space character, preferably a space.

4.4

Class Header

If the language supports the idea of classes then each class definition should be preceded by a comment block giving the class name followed by a description of the class. Inclusion of additional information about the class in the header is encouraged.

4.5

Function Header

All complex or not easily understood functions (procedures or methods) should be preceded by a comment block which gives the function name, a brief description of the function, a brief description of the parameters and a brief description of the possible return values. Inclusion of additional information about the function in the header is encouraged.

4.6

Deviation from Standard

If it is necessary to deviate from this coding standard for any reason, then the source code will include a file named ESP30Notes.txt that contains an explanation of which rules were violated and why.

ESP-30

Confidential

Page 3 of 10

5.0
5.1

Additional Standards for C and C++

Comments
All comments for C++ source code will start with //. For C source code it is acceptable to use the /* */ for comments.

5.2

Function Description Block

A function header in the following format should be provided before each complex or externally called function:
//*************************************************************************** // Function Name: <name of function> // // Description: <brief description of the purpose of the function> // // Input Arguments: <one line for each input argument containing the name of the // argument, followed by a hyphen (-) followed by a brief description of the // purpose of the argument. If no input arguments are used it simply enter NONE> // // Output Arguments: <one line for each output argument containing the name of the // argument, followed by a hyphen (-) followed by a brief description of the // purpose of the argument. If no output arguments are used it simply enter NONE> // // Return: <a comma separated list of the possible return values, followed by a // hyphen (-) followed by a brief description of the meaning of the return value // If there are no return values simply enter NONE> // // Globals Reference/Changed: <one line for each global variable that may be // referenced in the function. If no global variable are referenced simply enter // NONE> // // Exceptions: <a comma separated list of the possible exceptions that may be // thrown, followed by a hyphen (-) followed by a brief description of meaning // of the exception. If there are no exceptions possible simply enter NONE> //***************************************************************************

5.3

File Layouts

Source files should be structured the same way. The following segments should appear in the order indicated: 1. Source File Header 2. System #INCLUDES 3. Product #INCLUDES 4. Local #DEFINE symbols 5. External Global Symbol Declarations 6. Function prototypes Note that unused sections need not be included.

5.4

Identifiers

Identifiers should follow the conventions from the General Guidelines section with the following additions for C/C++: o o Identifiers created in #defined: directives are to be in all capital letters with underscores used to separate words (example: PAGE_HEADING). Global variables will begin with g_. The rest of the name will follow the general rules for identifiers (example: g_printerPort). Confidential Page 4 of 10

ESP-30

5.5

Literals
For C source code use named #defines. However for C++, do NOT use #defines, use named constants instead.

Avoid the use of literal numbers:

For example the following should not be used: maxDays = 7. Instead a named constant or #define should be created, so that the following could be used instead: maxDays = DaysInWeek - ormaxDays = DAYS_IN_WEEK .

5.6 5.7

Pointer Operator Brackets

The pointer operator (*) should be placed next to the variables on declarations.

In a block of code surrounded by brackets ({}), the code should be indented a tab space but the brackets should not (i.e. the brackets should be at the same level of indentation as the conditional clause to which they are related).

5.8

Include Files

All include files should use #ifdef statements to avoid multiple inclusions of data objects and class declarations. The defined constants name should be prefixed and suffixed by two underscores and should follow the naming rule for constants, e.g. #ifdef __OFFICE_PRINTER__

5.9

Namespaces

To avoid naming collisions with objects created for other products, namespaces should be used. These namespaces should provide and indication of the product or group of products that they are used for. For example: code for the Ultra-Link may use the name space Sensormatic.Ultralink or a general EAS library may use the namespace EAS.

5.10

Library or Component Files

For compilers which dont support namespaces, globally visible names (for variables, functions, classes, etc.) from a library or component should begin with unique prefixes that identify the group of products the system belongs to. For example EAS product identifiers should start with EAS_.

5.11
o o o o

File Naming
Template files should end with the suffix .icc. C++ Source code implementation files should end with the suffix .cpp. C source code implementation files should end with the suffix .c. Header files for both C and C++ should end with the suffix .h.

Use the following file naming conventions, unless precluded by the development tools.

5.12

Header Files

Do NOT use the using keyword inside header files. This has the undesirable affect of promoting all identifiers from the specified namespace to the global namespace for ALL files which include the header. Instead, explicitly specify the namespace for types used inside the header file. For example, when declaring a string variable from the std namespace, declare the member variable like so: std::string m_myString;

ESP-30

Confidential

Page 5 of 10

5.13

Keyword/Data Type Naming

Do NOT use #define for creating short hand abbreviations for in-built C/C++ data types or keywords. Use the full keyword/data type name. Where it is necessary to #define the data types for platform portability, use the following names for the defines: #define unsigned int UINT32; #define unsigned char UCHAR; #define unsigned short UINT16; #define char CHAR; #define int INT32; #define short INT16;

5.14

Global Variable Declarations

Avoid overuse of global variable declarations. This is a sign of bad design. Code should make sensible use of local variable declarations and, in the case of C++, class member variables.

5.15

Function Declarations

Although not necessary for compilation, all function declarations should name the function parameters as well as define the parameter types. This aids in understanding code and is necessary to support the use of advanced IDEs with context sensitive parameter help. For example, the following is not acceptable: void PrintMessage(string); Instead, the following should be used: void PrintMessage(string message);

5.16

Formatting If Statements

if statements must have the conditional statement placed within the braces on the lines following the if statement. For example: if(i < 10) { printf(hello); i++; } Is not acceptable, the conditional statement needs to be placed on the lines following the if statement, e.g.: if(i < 10) { printf(hello); i++; } The only exception to this rule is where the conditional statement is not a compound statement (i.e. it is a single statement), in which case the conditional statement may be placed on the same line but must be separated from other lines with blank lines in order to ensure readability. For example, the following is acceptable: if(i < 10) printf(hello);

ESP-30

Confidential

Page 6 of 10

5.17

Formatting Loops

All loops must have the loop statements placed within braces on the lines following the looping keyword(do, while, and for). For example: while(i < 10) printf(hello); Is not acceptable, the loop needs to be placed on the lines following the while looping keyword, e.g.: while(i < 10) { printf(hello); }

5.18

Formatting Switch Statements

All switch statements must have the switch block placed within braces on the lines following the line with the switch keyword. For example: switch(i) { case 0: printf(none); break; case 1: printf(one); break; default: break;} Is not acceptable, the switch block needs to be placed on the lines following the switch statement, e.g.: switch(i) { case 0: printf(none); break; case 1: printf(one); break; default: break; }

5.19

Code Organization
Modules

5.19.1

Code should be appropriately split into modules (units of code with a .c/.cpp implementation file and a .h header file) in order to ensure modular and maintainable code. 5.19.2 Functions

Code should be appropriately split into functions to ensure readability and maintainability of code. As a gross rule of thumb, developers should consider splitting a function into multiple sub-functions when the function exceeds 100 lines of code. Functions should NOT exceed 300 lines of code.

ESP-30

Confidential

Page 7 of 10

6.0
6.1

Additional Standards for C#

Comments
All comments will start with "//". The use of the alternate commenting construct ( /* and */) is discouraged and should only be used for the temporary removal of code during debugging.

6.2

Class Header

In general, all classes and interfaces should be preceded by a summary description header. /// <summary> /// class name- description of class /// </summary>

6.3

Function Header

All complex or not easily understood functions and functions which may be used by third parties should be preceded by a summary description header. /// /// /// /// /// /// <summary> Description: description of function </summary> <param name="parameter name">parameter description</param> <returns> possible return values </returns> <exceptions> possible exceptions that may be thrown </exceptions>

(Note: A header in this format is automatically generated for you by Visual Studio .NET when you enter /// on the line prior to the function declaration)

6.4

Source File Layout

Source files should use the following regions in order as needed: a. User defined constants and enums b. User defined member variables c. Private member variables (auto generated) d. Forms control events e. User defined methods f. Windows Form Designer generated code.

Creation of additional regions is encouraged to improve readability. However, remember the code in a region should form a logically related grouping of members. Note: Use of the #region directive is encouraged if your development tool supports it. Code will be appropriately split into modules in order to ensure modular maintainable code. All substantial classes in excess of 50 lines of code shall be placed in their own file. No file shall be larger then 300 lines of user generated code. Applications that have a requirement for internationalization should use resource files to store the strings displayed to the user. This will make it easier to translate the user interface into another language. However, it is recommended that this not be done until the later phases of development (post RP4) to avoid the extra work of making numerous changes to multiple resource files.

ESP-30

Confidential

Page 8 of 10

6.4.1

Naming Conventions

Static class variables will begin with g_ with the balance of the variable name following the general rule for the separation of words. For example: g_pageCount. Enumerator values will start with a capital letter with the balance of the variable name following the general rule for the separation of words. This rule does not apply to the enumerator type itself. For example: Monday. Interface Names will start with an I and the next letter will be capitalized with the balance of the interface name following the general rule for the separation of words. For example: IPrinterAccess. Properties will start with a capital letter with the balance of the property name following the general rule for the separation of words. For example: Position. Controls and components such as labels, text boxes, data sets, combo boxes, and buttons will start with a capital letter with the balance of the control name following the general rule for the separation of words. The last three to six letters of the name will be an abbreviation of the type of the control such as Lbl for label, DatSet for data set, Btn for button, or Cmb for combo box (example: PrintReportBtn).

6.5

Literals

Avoid the use of literal numbers (so called magic numbers), use named constants instead. For example day = DaysOfWeek.Sunday; is preferred to day = 0;

6.6

Statement Formatting
In a block of code surrounded by brackets {}, the code will be indented a tab space but the brackets should not, the brackets should be at the same level of indentation as the statement to which they are related if(isOpen) { isOpen=OpenDoor(); VerifyDoorOpen(); }

'if' statements must have the conditionally executed statements properly indented and placed within a block with separate lines for each statement. For example: if(i < 10) { Display (i); i++; } The following is not acceptable: if (i < 10) { Display(i); i++; } if(i < 10) Display(i); // Not allowed. // Acceptable However, single statements are allowed on a single line without the curly brackets: // Preferred

All loops must have the looped statements properly indented and placed within a block with separate lines for each statement. For example: int i = 0; while( i < 10 ) { i++; Display(i); }

ESP-30

Confidential

Page 9 of 10

The following the loop statement is not acceptable: while (i < 10) Display(i); // Not allowed. All switch statements must have the case statements properly indented and placed within a block with separate lines for each statement. For example: switch(i) { case 0: Display(none); break; case 1: Display(one); break; default: break; } The following the switch statement is not acceptable: // Not allowed switch(i) { case 0: Display(none); break; case 1: Display(one); break; default: break;} The braces for Function blocks should be at the same level of indentation as the function declaration. For example: public bool OpenDoor() { if(IsLocked) { UnlockDoor(); } ActivateOpener(); return true; }

6.7

File Naming Conventions

Unless the development tools require differently, the following file naming conventions will be followed: C# Source code implementation files will end with the suffix .cs. Resource files shall end in .resx. Configuration files shall end with the suffix .config.

6.8

Namespaces

To avoid naming collisions with objects created for other products, namespaces should be used. These namespaces should provide an indication of the product or group of products that they are used for. For example: code for the EOS may have the name space Sensormatic.EOS or a general RFID library may use the namespace RFID.

ESP-30

Confidential

Page 10 of 10