Coding Guidelines Why a Style Guide?

In the process of developing and maintaining software products it becomes increasingly obvious that the expense of maintaining and enhancing a product over its life can be significant. To help ease some of the expense certain coding conventions can greatly help. Our primary goals include: maintainability, portability and efficiency in that order.

Maintainability

Any software project is worth undertaking only if the methods and development techniques used are maintainable. Making the code understandable to humans is a primary concern in the maintainability of code. It is easy to generate a program that the C compiler can understand, but if a human does not understand it, then the program is worthless in the long run. Mainly because any enhancement or repair that might be needed would most likely cause a major rework or rewrite of the code.

Portability

In the modern computing environment of multiple platforms, it is crucial that our source code for our products be as portable as possible. Even if we have no immediate need to run our applications on an alternate platform, we may very well need to in the future (as an example Intergraph has already used 5 major platforms in our history). There are several things to remember when developing portable code.

1. Write portable code first. Implement optimizations or machine dependent code only when required.
2. Recognize that some aspects of a program or subsystem are inherently non-portable, such as device drivers, window systems, etc..
3. Plan ahead for portability. Retrofitting or force-fitting a port can be a maintenance nightmare or even impossible without a major redesign/coding effort.
4. Portability takes a lot of careful detailed practice. Don't think that you are going to get it perfect on the first try.
5. Don't be afraid to rework some subsystems to allow for better porting. (corollary to the second point)
6. Just because a compiler or linker "should", doesn't mean that it "will." In other words not all compilers or linkers are the all encompassing or all forgiving systems that we would wish them to be.
7. If your application is moving to different; hardware or operating system or file system or windowing/GUI environment or even just a different compiler and development tools, then you will need to plan on porting.

Always remember, take your product to the customer. Don't ask your customer to come to you.

Efficiency

It should be noted that the performance issues are listed last in importance. This is primarily due to the fact that if the code is not understandable and if it can not run on the machines that we need it to run on then it doesn't really matter how fast it runs! There are some good practices that can and should be used to provide better performance without sacrificing maintainability or portability. An overall good design is more important than micro-optimizations.