Five easy to avoid programming mistakes

When reading source code, i often wonder, why it is so hard to understand. This applies for code from others as well as for my own code i wrote some time ago.

Here are some tipps that could make maintaining and reading your code a bit easier.

Dead Code

Many programmers tend to comment out their code, if they want to test something. This leads to dead code:

int a;
cin >> a;
// Old Test, no more needed
/*if (a>=20) {
 doSomething()
}*/
if (a>=30) {
 doSomethingElse()
}

Of course, the above example is very trivial, but if the doSomething-Routines are sufficiently long, and the commented-out code is too much, you get a mess of no more used code. So just refactor it and remove the code you don’t need anymore:

int a;
cin >> a;
if (a>=30) {
 doSomethingElse()
}

Tricky constants

Often, we use integer numbers to identify something. Let’s consider a function that takes an integer as argument and interprets it as something special. In our case, the number stands for a mathematical operation:

int calculate(int a, int b, int operation){
 if (operation==1) return a+b;
 if (operation==2) return a-b;
 if (operation==3) return a*b;
 if (operation==4) return a/b;
}

If our constants are not as simple as in the example above, we can easily forget, what they stand for. For that reason, it is better to define them as constants somewhere and checking against the constants:

#define OP_ADD 1
#define OP_SUB 2
#define OP_MUL 3
#define OP_DIV 4
int calculate(int a, int b, int operation){
 if (operation==OP_ADD) return a+b;
 if (operation==OP_SUB) return a-b;
 if (operation==OP_MUL) return a*b;
 if (operation==OP_DIV) return a/b;
}

Long and confusing methods

If method definitions are too long, they are much harder to handle. If one discovers lenghty methods, it could be a sign that the problem isn’t split up well enough into smaller subproblems. So source out some passages of the code to make it easier to read and maintain.

A rule of thumb says, that every method should fit on a single screen page so it can be read completely without scrolling.

Ugly looking code

I often come across code that isn’t well-formatted. That is, there is (almost) no indentation, no whitespace, etc…

Consider the following example snippet:

void bubbleSort(int *a,int l){
for(int j=l-1;j>0;--j){
for(int i=0;i<j;++i){
if(a[i]>a[i+1]){
int tmp=a[i];
a[i]=a[i+1];
a[i+1]=tmp;}}}}

Of course, the above example is extreme. But it is quite easy to do it more nicely:

// *a   array to sort
//  l   size of the array
void bubbleSort(int *a,int l){
   for(int upper=l-1;upper>0;--upper){
      for(int pos=0;pos<upper;++pos){
         if(a[pos]>a[pos+1]){
            int tmp=a[pos];
            a[pos]=a[pos+1];
            a[pos+1]=tmp;
         }
      }
   }
}

Describe the arguments to a function (if not obvious). If necessary, allow yourself to use whitespace. That structures the code enormously.

Don’t use superflous comments

Consider the following snippet:

float p(int s){
   // initial value of result: 1
   float res = 1;
   // do s steps
   for (int i = 1; i < s; ++i){
      // calculate reciprocal value and add it.
      res = 1 + (1/res);
   }
   return res;
}

Do you know what it does? If not, see the snippet below:

// approximates the golden ratio (~1.61)
float p(int s){
   float res = 1;
   for (int i = 1; i < s; ++i){
      res = 1 + (1/res);
   }
   return res;
}

Give comments that explain the things you can not see directly from the code.

Or even better, use appropriate describing method names (if possible). (Thanks to gutzofter for his hint.)

float approximateGoldenRatio(int steps){
   float res = 1;
   for (int i = 1; i < steps; ++i){
      res = 1 + (1/res);
   }
   return res;
}

Conclusion

Even if it seems quite simple to follow these common sense tipps, it is often more difficult than one might think.

It is useful to control the code from time to time end eventually refactor it, so it can be read better. To put it in a nutshell: