Leinninger.com

What is good code? Any developer with a few years of experience will provide a different answer. My answer is simple: do the most with the least. This simple rule dominates even nature itself. Overly complicated systems require greater upkeep and maintenance. During the early evolutionary stages of our planet, overly complicated species faded into genetic obscurity. Early programing languages followed the same pattern. Complication without reason will only breed more complication.

Today, many developers openly brag about their 250,000 line application: “Just let (the next guy) try to figure THAT out!” Although this may ensure job security, it is truly no way to better your development environment. What is to be gained by a 250,000 line application that performs the same task as a 10,000 line script? Unless you’re paid by the bit, nothing.

A little over a year ago, our team inherited code from another group. We’re responsible for a major online financial resource, offering information and services to tens of thousands of visitors daily. Our team is web targeted and trained. We know good code, back end to front end. The original team consisted of desktop application developers accustomed to long development cycles, endless code, and poor communication. They built the original site as if it were a desktop app. That’s all fine and good if you’re in a market that moves at a snail’s pace, but the financial marketplace is constantly redefining itself. We couldn’t afford to have six month code cycles.

The first thing to go were object oriented (OO) tools for generating html. I’m not just talking about off-the-shelf products. The old team actually wrote Visual Basic and C++ applications to generate and/or compile their html for them. While I can appreciate the inner workings of their code, I can’t justify it’s use. With such tools we lost all flexibility. The smallest change required the use of cumbersome tools and a lot of waiting. Rule 1: If you can code it by hand, do so. Application wizards and assistants can be useful if you’re stuck. We must remember, however, that these tools were developed to help everyone to anything. A specially tailored code solution will to the job as well, if not better, with less code.

Another thing we noticed almost immediately was the complete lack of inline comments in the code. The comments that were found were more enigmatic than the code itself. Clear comments will help you when writing your closing docs (covered later) and assist when you have to debug your code later. In most cases, comments cause no extra bloat in modern code. Compilers ignore them, as do most modern runtime interpreters. The one glaring exception to this is HTML. Not only will those comments cause code-bloat, they can be a little too helpful to some visitors snooping through your code.

Reusable code is key. Not only can it save time, it limits possible points of failure while reducing the total number of lines of code. Although good reusable code may take longer to prepare initially, you will save time in the long run. Be prepared for future features, but you don’t have to implement code for them. A lot of the excess code in the old site was placed there for future changes that never happened. (Some things were as surplus as directories for features that were never needed or even planned on!) Simply recognize that changes will be made at some point to some of your code. Don’t code it into a circle. Make sure others can add to it easily. (Use clearly defined variables, group similar functions together, etc.)

Agree on a standard for variables and general code format early in the development cycle. If existing projects established these standards already, use them. Depending on your environment, you may have different formatting standards for different languages. Keep this to a minimum whenever possible. When size restrictions permit, limit the use of obscure abbreviations. (You may know that intlStatMtd means “internal status method”, but somebody else most likely won’t, unless you’ve established this in a comment or doc.)

All coders hate writing documentation, yet we all complain when we have to work on a project for which there is none. It is a necessary evil. There are a few things we can do to make writing and maintaining docs a little less painful. Use a template; most pro shops have established doc templates with an outline of the suggested content ready for you to fill out. If your shop does not yet have one, find an example of one you like on the internet and present it to your team leader. You’ll get a gold star on your forehead as well as some peace of mind. If you’ve included good comments in your code, consider yourself half-done already. Start cutting and pasting. Most projects start out with a spec. Most of the intro content for you doc can be pulled directly from the spec. Finally, remember to update your docs when changes are made to your code.

All in all, good code is the result of conditioning:

• Brevity is bliss. Nobody likes a joke that takes forever to get to the punch line. (Exception: Comeback College. Ask George.)
• Stay away from packaged solutions. They’re for everyone, not just you.
• Write good comments, it’ll help if you fall on your head mid-code.
• Write methods and functions that can be reused. Nobody likes code-bloat.
• Standardize your code format. It just looks so damn pretty.
• Write and maintain accurate documentation. You can tell your friends that you’re a programmer and an author.

Well, what are you waiting for? Why are you reading this? Don’t you have code to write?! Get to it!

Further information and related links: