Software Development Guidelines 03a

At my company I have seen a lot of bad software development practices over the years, so I have created a set of software development guidelines to help establish a set of best practices and baseline software requirements. I am publishing a series of experts from those guidelines here so that I might get some useful feedback that will help improve them.

• 01 - Introduction
• 02a - Planning
• 02b - Administrative Specification
• 02c - Requirements Specification
• 02d - Platform Specification
• 02e - Software Repository
• 03a - Development
• 03b - Documentation
• 03c - Security
• 03d - Quality
• 03e - Uncoupled Configuration

Development

Accessibility

It is important when writing programs to allow access to people with disabilities. Creating software that is accessible by people with disabilities is relatively easy since most modern operating systems have already incorporated these features. The main goal of the developer in this regard should be simply not to interfere with the features already provided by the operating system.

When developing web based applications we should strive to meet Web Content Accessibility Guidelines.

In the cases where overriding operating system accessibility defaults is necessary or when custom controls are created, the following points should be followed:

• Provide keyboard equivalents or shortcuts for all common actions.
• Do not interfere with keyboard accessibility features built into the operating system. These features vary between operating systems, so check the documentation of the target operating system before using custom shortcuts.
• Provide a visual focus indicator that moves among interactive objects as the input focus changes. This focus indicator must be programmatically exposed to assistive technology. Most modern operating systems will do this automatically.
• Associate labels with controls, objects, icons and images. If an image is used to identify programmatic elements, the meaning of the image must be consistent throughout the application.
• When electronic forms are used, the form shall allow people using assistive technology to access the information, field elements and functionality required for completion and submission of the form, including all directions and cues.
• Provide an option to display a visual cue for all audio alerts.
• Provide text through standard system function calls or through an API (application programming interface) which supports interaction with assistive technology.
• Use color as an enhancement, not as the only way to convey information or indicate an action.
• Support system settings for high contrast for all user interface controls and client area content.
• Inherit system settings for font, size, and color for all user interface controls.
• Provide documentation in an accessible format.
• Test for accessibility using available tools.

Coding Standards

All applications should follow generally accepted good programming practices as applicable to the programming language or application at hand. Here are some general recommendations that should hold for almost all programming languages and applications:

• All source code should be clearly commented.
• All source code should be indented to provide legibility [in languages allowing it].
• Variable and object declaration and naming should be consistent.
• Use code blocks rather than single line conditionals.
• All forms should have proper data validation and error checking
• Error trapping should be used so that in the event of a failure the program fails gracefully and supplies a meaningful error.
• When modifying another developer’s source code follow the same style that the original code uses. The original code will likely be around for a longer time than you may want to dedicate to it, so keeping your contributions consistent with respect to style is more important than forcing your programming style on the code.

Common ‘Look and feel’

This may be one of the most important software design guidelines and yet it is often overlooked. A common ‘look and feel’ is what makes Microsoft Windows (or OS X or KDE) such an intuitive platform; it makes it possible for someone familiar with Microsoft Word to easily transition to working with Microsoft Excel. This commonality allows users to feel comfortable with new programs and reduces the training time and costs. All programs written for use in the Company should be designed to match the operating system they are written for.

It should be noted that this paragraph does not mean that when an application is being ported from one operating system to another the look should stay the same as the source system. An application does not have to look like it did on the old operating system if this sacrifices commonality on the new operating system.

Developer Limitations

Software developers should generally not have programmatic access to production resources. In other words, developers should not be accessing production resources directly nor should they be writing applications that attempt to self update themselves or other software components in the production environment.

The use of application loaders and auto update mechanism should be eliminated in favor of the standard client installation tools (e.g. NetInstall).

Data Access Limitations

Developers outside of IT will generally not be given access to programmatically retrieve data from central Company systems such as SAP. The only exceptions to this rule are data sources that are available to all Company employees, such as Active Directory.

Developers should not have the ability to change any database schema on a production server. Database schema changes should be scripted, tried and tested on development servers, and turned over to the server group. The server group will use the supplied scripts to update production database schemas. This is necessary in order to accurately document changes to the database schema over time and provide roll back opportunities.