Touch Technologies, Inc.
Coding Standards


Previous Contents Index


Appendix A
Coding Principles and Standards

As defined by Rick Cadruvi

[email protected]

To program well you should not have to think too much about the actual code. Making the code simple and easy to understand is where your thoughts should be. It is the logic/problem-solving part of programming that requires 90% of the thinking.

Always choose to write code as simply as possible. It's often tempting to do "clever" things, but simple code is what pays off in the end. At some point in the future, you or someone else will need to look at the code and understand it... quickly! Too much time is wasted by programmers trying to interpret what another programmer (or they, themselves) did in a program or routine.

Writing the programming code is just creating the flow of logic needed to achieve the purpose of a program. So keep it simple and on track.

Think ahead when programming. Assume that the code you're writing will be useful in the future--then make it easily reusable and therefore somewhat generic (including re-entrant). It's worthwhile to take a few extra minutes to ask yourself: "What should this routine look like to make it easily used in the future for similar projects?" When working on a project, separate out dependencies such as calling something "operating system specific" or limiting it to a certain file specification. It is guaranteed that you will want to run this code on a different platform, or use a different file specification, at some point in the future.

To create professional looking code, here are some basic guidelines:

The code must be kept SIMPLE and CLEAN.

Code should always be neat in appearance and well-documented in each routine header.

Always take extra time to write the initial code. 95% of code should work the first time if it's written with care.

Put each small "concept" within the program into a separate routine. This is the single most important point about program structure. Use subroutines as a packaging mechanism to organize the individual thoughts and concepts in the program. The size of a concept will be subjective, but the smaller the thoughts or concepts you break a program into, the more successful you will be writing code.

Each routine should be under 25 lines. If the number of lines exceeds 25, the routine is becoming too complex. If your code no longer fits on one screen, you really need to ask yourself: "WHY?" There should be many routines and subroutines written.

There are exceptions, however. CASE/SWITCH-type statements where the number of cases is very large can make a routine much longer than normal. In such instances, the individual cases should translate to routine calls to do the work rather than inline code.

Keep columns short (up to 80 characters). Many people use Notebook computers or have smaller monitors. Keeping the columns to 80 characters or fewer guarantees that all of the code will appear in the screen area. This will keep the viewer from having to scroll horizontally to see the ends of the lines.

Avoid more than three levels of indentation (nested LOOPS and IFs, etc.). Three levels or fewer keeps the code in a routine from becoming too complex. If there are more, then an inner loop should be moved out to a new routine. This keeps the code looking neat, clean, and easy for the reader to follow.

Be consistent with names within the program. Making up different names for the same thing is too difficult to follow. Variables and routines should be named in a manner that explains their meaning. Additionally, strive to keep names short and simple.

Always line up "=" signs. When declaring variables, list them alphabetically to make them easy to find. Initialize variables at the top of the routine.

Avoid doing IF ELSEs. IF ELSEs complicate code. For example, a well-written program that contains 25,000 lines of code (including comments) might have approximately 20 ELSEs compared to over a thousand IFs. This illustrates how rare an IF ELSE should be. If an IF ELSE is necessary, then the IF should be the short line of code, and the ELSE the long line.

Use RETURN statements as soon as possible within a routine. Do not wait until you get to the bottom of the routine. This will eliminate a LOT of ELSEs and funky loops and BUGS!

Always make the call, then test the result in the conditional expression statement. In general, never set variables to something, or test the result of a function call in an IF, DO or FOR expression.

Use parentheses around every set of operations. This makes it easy to determine the beginning and end of an operation. It also makes it absolutely clear what you intended, without depending on the order of precedence of operators. If someone reading the code can know with absolute certainty how you intended it to be executed via the use of parentheses, then they will not have to wonder if the language you used created code other than what you intended it to create. For example:

if a > b * c or d + 4 = f then x = x + 1

if ((a > (b * c)) or ((d + 4) = f)) then x = x + 1

Code should be language-independent. Code should be written so that programmers of all kinds of different languages can understand it. All languages have more or less the same constructs. There are language-specific items that will be unavoidable, but they should be few and far between. They should not get in the way of someone understanding the code, even if that person has never programmed in that language before.

Make code easy to understand quickly. It should take no more than 30 seconds to understand a line of code, and no more than 10 minutes to understand a routine. If the reader has to sit down and figure it out, the code is poorly written. Poorly written code is guaranteed to have bugs!

Avoid writing extraneous code. When writing the code, ask yourself: "Is this code really necessary?" Extraneous code makes for a complicated routine and is difficult to understand later. Once in a while, however, it is necessary to include some extra code purely for the sake of clarity.

Make code understandable and concise. Think about the code just written and see if there's a shorter, more concise and understandable way of writing it. However, sometimes taking a shortcut to write the code smaller can make it LESS understandable--so keep in mind that understandability is the main goal!

Always do a thorough code review before you compile it. A code review should enable you to find the logic flaws even before the first compile. The majority of errors will then be compile errors--and generally trivial ones at that. When you start your code review, ask yourself: "What did I do incorrectly?" Get into the mindset that your code has errors/bugs as opposed to thinking, "Of course it's right---I wrote it!" It's easier to find your errors when you're expecting them rather than using *selective vision* during your review.

Focus on writing good code, not debugging bad code. **A good programmer is one who spends very little time working with debuggers. Don't focus on debugging your code--focus on writing code that doesn't contain any bugs!**

Test the smallest parts of code. Take the routine and write a program to test it. Later when you go back to that code, you will know that routine will always work unless some changes were made to it. This can be particularly handy when having to debug, since the already-tested routine can be ruled out right away.

Always document code thoroughly in each routine header. Ideally, commenting should rarely be done inside the actual routine. If the routine is written simply and kept short, then no comments are needed within the code. Keep the size and scope of the routine limited and obvious for future reference.

Do not be afraid to rewrite or modify your code! When rewriting or modifying code, whether it's your own or someone else's, it's essential to have a backup copy of the ORIGINAL kept in a safe place. This way, if you need to scrap your changes, the original working copy won't be lost. You may lose the time that you spent doing the modifications--but at least you will still have what you started out with before making any changes. A second hard drive is recommended to store all programs for safekeeping.

Organize your routines in logical or alphabetical order. In shorter programs, the routines should follow each other in a logical order within the program. For longer programs with many routines, putting the routines in alphabetical order makes it easier to find a routine when needed.

Group routines into small modules. Every attempt should be made to group similar routines into separate source modules to keep module size smaller, which makes it easier to locate things. GLOBAL routines should be grouped together alphabetically, as should LOCAL routines.

The key to creating excellent code is in writing small routines that express individual thoughts/concepts.

Carefully writing your code and performing regular, thorough code checks can virtually eliminate the need for debugging--saving much time and frustration.

Most of the time spent on programming is NOT on the initial code creation itself, but in getting it to work, future modifications, and continuing to keep it working.

A good understanding of the purpose of the specific piece of code being worked on would help to create professional-looking code.

A programmer's creativity comes from the manner in which the problem is solved, NOT in the actual coding.

Always remember---the very best solutions expressed in code are the ones that any beginning programmer can understand.


Previous Next Contents Index