From Kietzman.org

Contents 1 Introduction 2 Coding Standards 2.1 Available Databases 2.2 Available Programming Languages 2.3 Commenting 2.4 Cron Jobs 2.4.1 Example 2.5 Debug Code 2.5.1 C/C++ 2.6 Error Handling 2.7 Makefiles 2.8 Modulizing Source Code 2.9 Source Code Header 2.10 Variable Naming Convention 2.10.1 Examples 2.11 Versioning 2.11.1 Example 3 File Locations 3.1 Data Storage 3.2 Executables 3.3 Base Code 3.4 Web Code 4 External Tools 4.1 C/C++ 4.2 PHP 5 Version Control

Introduction

This section describes essential practices of building a new application. When reviewing the standards, keep in mind that these practices were developed for support of the application later on. Please follow these instructions with care so that the developer after you will be able to support your work. Thank you.

Coding Standards

Available Databases

The following databases are available in our shop. Please use caution when using a non-standard database since supportability could become an issue.

Database	OS
MySQL	Linux

Available Programming Languages

The following programming languages are available in our shop.

Language Type OS Usage C/C++ compiled Linux base Expect interpretive Linux base Java compiled/interpretive Linux base Mynah interpretive Linux base Perl interpretive Linux base/web PHP interpretive Linux base/web Shell interpretive Linux base

Commenting

In order to assist maintainability there must be comments in the source code. Don't think that just because you understand the code, that the next person will.

At a minimum there should be a paragraph directly under the header that explains the purpose of the source code. Then throughout the code there should be comments that explain the inner-workings of non-intuitive sections of code.

The items above are requirements. Futher option would be to add comments above each and every function that explain the following.

• The purpose of the function.
• A description of all formal input and output parameters used.
• Significant restrictions and constraints, if any.

Cron Jobs

Cron jobs should always be placed in a mechanized account. They should never be run out of root or a developer's id.

Reference Item	Time Frame	Description
1	minute	0-59
2	hour	0-23
3	day of month	1-31
4	month of year	1-12
5	day of week	0-6 (0=Sunday)

Example

Ref. Item -> 1 2 3 4 5  
             0 6 * * 1 <full path to some command/application> [options]

NOTE: The above cron would run at 6:00AM every Monday. The star represents a filler for a location (don't care) and each location has to be filled in.

Debug Code

This code is optional, but is highly recommended because it can save you headaches down the road. Debug code allows the application to output vital parameters in real-time. You can design debug logic to show you values that are contained within any given variable at any given time.

C/C++

There are three ways of activating debug code using C/C++:

• A command-line option to which the application will respond.
• A -DDEBUG for the compile line that creates the object inside the Makefile.
• A #define DEBUG within the application source code.

NOTE: The latter two options that use the DEBUG define would both need to be recompiled before use.

The recommended technique is the command-line option. There is an example of this technique below.

app.cpp

#include <iostream>
#include <string>
using namespace std;

#define VERSION "1.4"
#define mUSAGE(A) cout << endl << "Usage:  " << A << " -v" << endl
                       << "v  -Gives the current version of this software."
                       << endl << endl
#define mVER_USAGE(A,B) cout << endl << A << " Version: " << B << endl << endl

bool gbDebug = false;

int main(int argc, char *argv[])
{
  for (int i = 1; i < argc; i++)
  {
    string strArg = argv[i];
    if (strArg == "-d" || strArg == "--debug")
    {
      // Turn debug mode on
      gbDebug = true;
    }
    else if (strArg == "-h" || strArg == "--help")
    {
      // Display a help message on how to use this application and options
      mUSAGE(argv[0]);
      return 0;
    }
    else if (strArg == "-v" || strArg == "--version")
    {
      // Display the software version of this application
      mVER_USAGE(argv[0], VERSION);
      return 0;
    }
    else
    {
      // Error handling if wrong option entered
      cout << endl << "Illegal option, '" << strArg << "'." << endl;
      mUSAGE(argv[0]);
      return 0;
    }
  }

  if (gbDebug)
  {
      // Debug code to display
      cout << "Some debugging information." << endl;
  }

  return 0;
}

Error Handling

Error handling should be used in all aspects of coding. This will help in keeping your applications from hanging, core dumping, terminating unexpectedly or executing when the program should be terminating. Error handling should be implemented in base code, web code, databases, and cron jobs.

A good example of when this should be used would be when catching an error from a database call so that the program can perform the appropriate response.

Please see Error Handling Instructions for further details and examples.

Makefiles

Makefiles are used to prepare applications to run in the system. They have many similarities to working with shell as you will see. A Makefile's functionality comes from its ability to follow labels according to their dependencies.

The Makefile should reside in the same directory as the source code.

Capabilities

• Check and fetch dependencies.
• Compile source code into object code.
• Compile object code into binary executables.
• Build test suites.
• Install executables into the system.
• Clean the source directory.
• Uninstall executables out of the system.

There are many flavors of Makefiles, but for the most part they all function using the same command-line calls.

Typical Commands

 make
 make install
 make uninstall
 make clean

Please see Makefile Instructions for implementation and detailed examples.

Modulizing Source Code

Code modulization basically means that when a section of logic within source code is repeatedly used, it should then be seperated out into a module. This technique applies to both base and web code, but is implemented differently depending on the language. The overall purpose of modulization is to avoid reinventing the wheel. By doing so you will help shorten the software development lifecycle and reduce the amount of possible bugs in the software.

A good example of when this should be used would be when seperating out logic for repeated database calls.

Please see Modulizing Source Code for further details and examples.

Source Code Header

The following header should be included at the top of every piece of source code.

///////////////////////////////////////////
// <program name>
// -------------------------------------
// author     : <author's name>
// begin      : <MM/DD/YYYY>
// copyright  : <company name>
// email      : <email address>
///////////////////////////////////////////

Variable Naming Convention

There is a standard variable naming convention called Hungarian Notation. The notation is used to help define variables for easier readability of code. By strapping a prefix onto a variable name, you can identify its variable type without visually seeing its definition. The notation is primarily used in C/C++ code but can be carried over into other languages also.

The following prefixes should always prefix a variable name when they are initially defined in the code:

Type	Prefix
float	f
double	d
boolean	b
long	l
int	i
char	c
string char array	sz
pointer	p
structure	t
global	g
constant	k
unsigned	u
string object	str

Examples

char szFilename[256] = “\0”; // string character array
int nCount = 0;              // integer variable
const int knTimeout = 24;    // constant integer variable
unsigned long ulTime = 0;    // unsigned long variable
bool bResult = false;        // boolean variable
const float kfCirle = PI;    //constant float variable
FILE *pFilename;             // pointer to a file
typdef struct months
{
  short nMonth;
  char szMonthname;
} months_t; 
months_t tCurrentMonth;      // structure holding month information

Versioning

All applications should be capable of displaying the current software version number. The displayed software version number should match the release production version in CVS.

Base applications should respond to at least one of the following command-line options by returning the version number: -v or --version. This becomes most beneficial when there are multiple releases of an application across various servers. It's up to you where you place the version numer in your code. For C/C++ it is typical to make a define variable named VERSION that holds the version number.

Web applications should have a version number displayed in an inconspicuous place on the site. It should not stand out and grab someones attention. It is there purely for the purpose of trouble shooting. Typically, the version number would be placed at the bottom of the page in the footer or possibly under a menu.

When creating version numbers, please feel free to use your own versioning pattern. The following guidelines are purely suggestive. The important thing is that you version your applications in a logical manner.

Before an initial production version of an application is released, the version number should begin with a zero. For an existing application that is in production already, the version number should begin with a one and then climb from there.

Version digits follow a general pattern:

• first digit - large changes
• second digit - medium changes
• third digit - small changes

Example

Version	Reason
0.0.0	initial pre-production release
0.1.0	added two new functions
0.1.1	changed some variable names altered the text of an output stream
0.1.2	added some file error handling
1.0.0	initial production release
1.0.1	changed a defines value
1.1.0	added an additional menu item
2.0.0	rewrote in a better programming language

File Locations

The location of files within the servers is vital. We must maintain consistancy in this area. The following file location standards apply only to Linux servers.

There are four primary types of files that a developer will utilize: data, executables, base code and web code. You will find more details on each type below.

NOTE: Remember to turn on owner and group permissions. If customers need direct access to the files, then you will want to turn on other permissions as well.

Data Storage

When establishing an application directory always place the data files in the following directory structure: /data/<app-name>

Exceptions

• Anonymous FTP Feeds: /data/ftp/pub/<app-name>

Executables

When establishing an application directory always place the executables in the following directory structure: /sys/<app-name>

NOTE: Remember to turn on execute permissions for all your executables.

Base Code

When establishing an application directory always place the base code in the following directory structure: /src/<app-name>

NOTE: Source code should never be placed in a home directory.

All sub-directories for an application should be placed within the application directory: /src/<app-name>/<sub_dir>

Types of Sub-Directories

File Type	Extension	Location
Executables	<none>, .exe, .ksh, .php, .pl, .sh	<app-name>/bin
Classes Includes	.cpp, .h, .java	<app-name>/include
Objects	.class, .o	<app-name>/obj
Main Source	.c, .cpp, .java, .ksh, .php, .pl, .sh	<app-name>

Web Code

When establishing an application directory always place the web code in the following directory structure: /web/htdocs/<app-name>

All sub-directories for an application should be placed within the application directory: /web/htdocs/<app-name>/<sub_dir>

Types of Sub-Directories

File Type	Extension	Location
Cascading Style Sheets (CSS)	.css	<app-name>/css
Images	.gif, .jpg, .png	<app-name>/images
Javascript	.js	<app-name>/js
Classes Includes	.php	<app-name>/include
Main Source	.php	<app-name>

Cgi-Bin Executables When establishing an application directory always place the cgi-bin executables in the following directory structure: /web/cgi-bin/<app-name>

All sub-directories for an application should be placed within the application directory.

NOTE: Remember to turn on execute permissions for all your executables.

External Tools

There are many external tools which keep us from reinventing the wheel and shorten our software development lifecycle. The tools have been organized by their respective programming language.

C/C++

Tool	Location	Description
General Library	Doxygen	Provides a general set of object-oriented C++ tools.
libodbc++	libodbcxx.sourceforge.net	C++ Wrapper class for UnixODBC.
UnixODBC	unixodbc.org	ODBC Driver Manager

PHP

Tool	Location	Description
Calendar Class	Doxygen	Interface for displaying a calendar.
Database Class	Doxygen	Interface for access Informix, MySQL, Oracle and Postgre databases.
Document Class	Doxygen	Interface for implementing website layouts.
Email Class	Doxygen	Interface for sending emails.
Error Handler Class	Doxygen	Interface for managing errors.
MediaWiki	mediawiki.org	Wiki tool.
phpMyAdmin	phpmyadmin.net	MySQL database tool.

Version Control

Concurrent Versions System (CVS) is a standardized source code versioning software. It is a robust versioning software with many features. The CVS web tool is used to view source code changes between versions.

All base applications should be placed off the root of the repository while all web applications should be placed in the relative web path.

Examples

• Base Application: cvs co app
• Web Application: cvs co web/app

Please see CVS Instructions for implementation details.