C.1. General Guidelines

It is pointless being too prescriptive about programming style as programmers tend to have their own ways of doing things. There are however a few guidelines which you should try to follow when writing code for EMBOSS.

Use of libraries. It is very wasteful to write code unnecessarily; often the functionality is available in AJAX or NUCLEUS. Check the libraries before coding and contribute any new code so that it can be incorporated into the libraries.

Over-engineered code. A common mistake is to waste time implementing functionality that you think you'll need one day, but never actually do. Over-engineered code is confusing and difficult to maintain. Only program what you need today, but design your code so that it can, if necessary, be extended in the future.

Duplicated code. Duplicated code is error-prone and difficult to maintain. Do not duplicate blocks of code, write a function instead. Where two functions do essentially the same thing but have different arguments, make one function simply call the other.

Managing change to code. Your code should be easy to modify for new functionality. Where you find yourself modifying multiple objects or functions to implement a single change it's likely your data model or program structure is not ideal. Consider defining a new object containing the elements you need or new functions as appropriate.

Keep objects clean. The purpose of each element in an object should be obvious. Objects containing variables that are only rarely used or which are used for house-keeping, for instance to hold temporary values, can be difficult to understand. Review your code and establish whether the variable really needs to be in the object or whether it's best moved somewhere else.

Avoid redundancy. Where two or more different objects share common elements there is likely scope for removing redundancy throughout your code. Consider whether a new object encapsulating the common elements would make your code easier to understand and maintain.

Manage your variables. Functions with very long lists of variables are difficult to understand and maintain. Where a group of variables are always used together, consider encapsulating them in a new object, especially where the group occurs elsewhere in your code.

Long functions. Big functions are difficult to understand. Smaller functions are easier to document and therefore easier for the programmer to identify. Functionality split into smaller functions is more likely to be re-used. Consider breaking big functions down into smaller ones. If necessary, retain the function with the original name which can call the new, smaller functions. Do not overdo it though and try to avoid too many levels of function calls (see "Nesting of functions" below).

Long parameter lists. Functions with many parameters are difficult to understand, use and maintain. Where possible, you should pass an object pointer rather than the individual elements of a single object. If the parameters do not belong to an object, consider defining a new object to encapsulate them and pass a pointer to that instead.

Nesting of functions. Code which uses deeply nested chains of functions can be extremely difficult to understand. Design your code to avoid this.

The EMBOSS C coding standards are summarised below. Mostly they concern layout of the code, some well established principles of C programming, and tips for programming EMBOSS objects (C data structures) and functions.