Home > Computing > Basic principles of programming

Basic principles of programming

This post is meant to serve as advice for beginner programmers. If you don’t consider yourself a beginner, read on and check if you agree.

So here are a few basic principles which a programmer should follow to write good code, no matter what the language is.

When I started my adventure with programming back in fall of 1993, I wish somebody laid these out for me. There are many good books about the dos and don’ts of programming, such as Effective C++, but I think it’s still difficult to find to find the more simple basic principles like the ones below, esp. for novice programmers.

These principles apply to most areas of programming. They should be taught at the beginning of programming courses. Unfortunately most programming courses focus on tools, such as programming languages, environments, data structures, etc. but they don’t touch the craft and art of programming.

Copy & paste

When writing one of my first programs in Turbo Pascal, I quickly learned that pasting pieces of copied code around in a program leads to a lot of unnecessary work at a later time. Let’s say you have exactly the same piece of code in N places, and that code is meant to do the same thing, or even if there are N places with very similar code doing very similar thing. One day you will have to change that code slightly or enhance it. Or you will find a bug in that code. You will have to find all N places and apply the same change N times. There is a high probability that you will miss some of the places – the larger the N the higher the probability. This will lead to either not fixing existing bugs entirely or introducing new ones.

The takeaway from this is that multiple copies of the same pieces of code should be avoided. Similar code should be collapsed into one function and that function invoked wherever it’s needed. Avoid copy & paste.

Code clarity

Variables, functions, members etc. should be named after what they do. Most variables should be nouns. Most functions should be verbs (e.g. variable num_args vs. function count_args()). The names should be short, but long enough to give a clue to the reader what they mean. There are some schools which teach that variables should never have long names. This is OK, but in some circumstances it’s necessary to give longer names so that the reader can easily understand what is happening in the code.

There is another term for using meaningful identifier names: self-documenting code. When clear names are used, there is less need for comments and other kind of documentation.

Comments should be used whenever the names of variables, constructs etc. are not sufficient to understand what’s going on. This applies especially to more complicated pieces of code, algorithms, etc.

But why bother with all of this? One word: maintenance. Sometimes a person other than the author has to maintain the code – fix bugs, add new functionality, refactor or reuse. The less time that person needs to spend to understand what’s going on, the better. Often even the author may need to return to the code he’s written and may not remember why certain decisions were made.

Language constructs which promote bugs

Every language has constructs which promote bugs. Such constructs should be avoided. They may be useful or necessary in certain situations, but in these situations they are the necessary evil. In most other cases we’re better off without them.

Examples include: goto in C++, a bit less in C, C-style macros in C++, == operator in JavaScript.

In general any language feature which has gotchas, which may behave in an unexpected way (e.g. friend or protected in C++), should be avoided, unless specifically beneficial in a certain situation. When used, precise comments should be added describing the use case.

The unfortunate thing is that until you know a particular language really well, you don’t know what these tricky constructs are. They are usually not advertised in the language manuals. Sometimes there are books which help to learn about why particular features are dangerous. So the best advice one could give here is: stay alert!

Diligence vs. ignorance

Or I should say: willful ignorance. Programming has become ubiquitous and some languages like JavaScript have a very low entry-level. It’s good, but it also comes with some disadvantages, such as: programmers don’t put enough thought into what they are doing. I’ve seen too much mindlessly written code in my career. Some simply assume that they are writing throwaway code and they don’t care about the quality. Other just implement the first solution which came into their mind, they don’t try to think of all advantages and disadvantages of that solution, it’s like they only wanted to finish their current task and move on, as if the code they write was going to be thrown away right after being written, or as if they were going to quit soon and they don’t care who will be maintaining that. But the code tends to outlive the task, somebody has to maintain or extend it. This leads to the same piece of code being reimplemented over and over again multiple times, which is a huge waste. If the first implementor gave enough thought into what he was doing, the original piece of code could have been used for years, perhaps even reused.

The advice here is: be diligent. Learn about the environment surrounding the code you write (i.e. callers, callees, etc.). Learn about all the use cases. Try to think of all things that your approach may break. It does take experience to write good code, but it also takes common sense.

Code reviews

It’s good to have an additional pair of eyes review your code. If you’re writing code for fun, have a friend take a look at it. If you’re working for a company, have a coworker review your code and review his code in return. I don’t know why code reviews are not a custom at many companies. Reviews take only a small amount of time, but they have a big benefit of unifying the code to ease future maintenance, promote coding style conventions, promote good behaviors and suppress the bad ones, etc. It’s even more beneficial if somebody more experienced reviews your code, you will learn from him.

Reviews are not an ultimate solution, they will not help to find all bugs, in fact many bugs will slip through reviews, but reviews help improve code quality in the long run.

Categories: Computing
  1. 7.05.2012 at 01:26

    Wow such a nice article.Thank you sir for sharing your valuable experiance and advice.I am a beginner in writing codes now an trying to get the best from C++.This post surely is gonna help me.

    • 7.05.2012 at 09:16

      Thanks, I’m glad somebody found this useful. 🙂

  2. 7.05.2012 at 01:27

    Reblogged this on All About Technology.

  3. Chris
    6.08.2012 at 12:02

    Nice article. I would add one important advice: organize your code into modules / functions / classes with separate and clear responsibility. There is nothing worse than a few hundred lines function which makes dozens things, from copying a file to brewing a coffee. Such code is hard to follow, test and maintain. Write a function which copies the file, another one which makes a coffee, and only then put them together. This will make your life much easier when it comes to making any changes in code logic.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: