Foreword

My primary programming language is PHP. I am going to try to keep these rules as general as possible, for they should apply in any programming situation. The one exception to that theory is in my readability section, some of the syntax may differ. I will draw my examples using PHP.

Grab your keyboard and the nearest shuriken. There will be blood shed by the end of this article!

 

1. Readability

There are a few simple techniques that you can employ to make your code more readable. Readability is important if you’re working on your own, or if you’re working with people. Readability is literally how your code reads and nothing more. There are other players in the overall ability to follow your code, and I will allude back to this section when we get there.

Key Factors in Readability

Whitespace

Whitespace is free, use it. I know some people may disagree with me here, and I’ve seen their atrocious code, but spacing out your code is very important. Think of your code as a book, you need to allow the eye to find breaks and segways easily so that you can scan your code and find the break point you’re looking for.

Figure 1 (Poor Formatting)

Since this is a small amount of code, one could discern it’s intentions pretty easily. But, Figure 2 will show you the difference. It should make you feel like you’ve just showered off the poor formatting and inhaled a fresh breeze of readability.

Figure 2 (Clean Formatting)

With the right amount of line breaks, indentation, and spacing, you can produce readable code. Obviously, too much of any of these will start to look bad as well. Find a good median and stick to it throughout the rest of your code.

Alignment

When you have many similar lines of code, ask yourself if they can be aligned or grouped in such a way that express similartiy and also make it easy to extract information from.

Figure 3 (Messy variable declaration)

Again, in the small scheme of things, this is readable. But, you need to picture this in the grand scheme of things. If all of your code is not written in a careful manner, when you come back to read it, or if someone else has to read it, it will become a nightmare as it grows. In Figure 4, you will see that it’s almost the same except the variable names and values are aligned and the variables of similar types are grouped.

Figure 4 (Organized variable declaration)

Variable Naming

If you want your code to be readable, you should use descriptive variable names. As Alisto said below:

The difference between amateur and professional (and maintainable) code is the amount of semantic load you are required to carry around with you as you navigate through the code. Less semantic load = more brain power available for understanding what the code does.

With modern IDEs and editors there is no excuse for using shortened names for classes, procedures, etc., this increases the semantic load as each time you come across one, you have to expand it to understand it.

For example, a variable called ‘cnt’ does this stand for ‘current’, ‘count’ or what? It gets even worse if ‘cnt’ is expanded to different things in different modules of the code (possibly written by different people).

I agree completely. You should not need to stop and figure out what a variable stands for.  If it’s impossible to express the variable’s contents simply by it’s name, then you should comment it and give a description.

2. Conformity

Conformity is very important in solo or group projects. It is all about keeping your coding style consistent throughout your entire application.

Solo

This can be harder to maintain on a solo level. As you begin to grow as a programmer, your techniques evolve. You can’t be expected to always go back and change all of your old code to reflect your new findings. Sometimes you will, but you can’t always do it.

Over time you will most likely begin to create your own library. A library, as you may know, is a set of code that you bring to every job. It’s basically your self-made toolbox. You begin to understand the need for functions and object orientation in order to make your life easier and reduce repetitive tasks. It is very important to keep your library fresh and take the time to tend to old wounds. Your library is your toolbox and you should make sure your tools are always cutting edge and sharp. If one of your tools grows dull, either sharpen it, or replace it.

Example

At one point in my career I had a set group of functions that I always included in my projects. One of them was called make_dropdown() which would take in an array of ids and their text equivalent and generate the HTML for the dropdown. I did this because it was getting old to always have to write a loop to populate dropdown menus.

Group

In college I had a professor Vic Berry, who made a great point that has stuck with me and should stick with everyone. When you’re joining a project, you shouldn’t push your own coding style. Make it easy for everyone and stick to the style of the project. If you’re making a plugin for wordpress, for instance, you should stick to the way the rest of the code looks in wordpress. Even if it’s atrocious. Why? Conformity in the grand scheme of things is very important.

If you’re reading through an entire project of code, you don’t want to see different coding styles all over the place. This prevents your brain from recognizing patterns. Even if the coding style isn’t to your liking, consistency is important and should be maintained to provide overall project readability.

3. Be Organized

This section plays into both Conformity and Readability. You should organize your files and code the same way throughout your entire project. If you have your includes at the top of the file, they should be at the top of the file in the same place in every file. Again, we’re building on the brain’s expectations and the way it handles patterns.

Code

If you don’t already know, in the software engineering world there is an architectural pattern called MVC (Model-view-controller). MVC separates the Model (database), View (Presentation, UI) and the Controller (what modifies the Model). I won’t go to deep into it here, because it’s an elaborate topic. It’s a great way to organize your code, though, and you should read up on it if you haven’t yet.

File Structure

This should also apply to your directory structure. If you’re naming a directory ‘lib’ in one place that contains specific files, it should be named ‘lib’ in another place that contains those similar specific files that pertain to that section.

Group similar files together. Javascript files go in js, CSS files go in css. Keep anything that doesn’t need to be accessed by the web outside of the web’s reach. Something like:

/home/website/website.com/public_html - Web accessible code (html, javascript, the “view”)
/home/website/website.com/system - System Code (functions, classes, dependencies, ajax functions)

4. Scalability

The ability for your code to scale is vital if you want to sell yourself as a programmer. It’s also vital if you’re supporting your own code and trying to expand it’s ability. The best way to approach scalability is to abstract things when possible. Even if you think you’ll never need to expand something, it’s good practice, and you can never be sure.

If you’re working on a larger project, try to avoid saying “We’ll cross that bridge when we get there”. Sure, cross the bridge, but make sure it’s built by the time you get there. It’s easy to cut corners and not take the extra steps in the early stages of a project. But, it’s very important not to rush and to think things through. The best example of a site that has had horrible scalability issues is Myspace which you can read about in this great article by David F. Carr titled Inside Myspace.

Example

Recently, one of my clients asked me to take their contacts database, which was only one table, and change it so they could have user-definable regions and contact groups within that region. When I had created the original contacts table, the region field was an enum(’US,’UK’,'Other). So, this is an example of how having some foresight could save you some trouble. I had to create the region table, then, update the contact table to have a region_id that corresponds to the contact’s and then update all of my code to reflect these changes.

5. Supportability

Sections 1-4 of this article all amount to this word: Supportability.

By making your code easy to read, organized, conformed, and scalable, you create supportable code. What is supportable code? Supportable code is something that is easily enhanced or modified or easily fixed. After you leave a project, if someone is given the task to fix a bug that falls in your region of code, the more supportable your code, the faster it gets fixed. People like you.

Comments

By now, many of you are probably foaming at the mouth waiting to point out that I haven’t mentioned comments. I’ve left it until the end intentionally. Comments are the most integral part of creating supportable code. While most of your code should tell a story on it’s own, there are times where comments will save you hours of work in the future.

When to use comments

• Functions. Comments are essential in describing the expected input, output, and purpose of a function.
• Complex logic. Use comments to give a human description of what is going on in the next several lines.
• Declaring variables. Indicate what the purpose of a variable is within its scope.
• Non-intuitive approach. When you are approach any situation with a non-intuitive approach, it is essential to comment.

When to avoid using comments

If you use comments all the time, they become less meaningful and defeat the purpose of having comments. Your comments will become diluted. Comments should be annotation, not narration.

• Don’t announce you’re going to // loop through vars
• Don’t comment if the code is redundant to your comment. // Checking if var is equal to 8

Conclusion

Every one of these techniques should become a habit. Each one of the sections in this article applies to each other, it’s almost incestuous. Organization requires conformity, conformity requires organizations, readability requires conformity, supportability requires everything, etc. It’s a vicious ninja star. Use it to tear through your enemies.

Buy me a beer if you liked this post or found it helpful