Summer holidays ahead, yay! This will be the time when my job is an enviable one. Having spent the last couple of weeks grading never ending piles of final exams and thesis projects I feel like I deserve it. Most of this time has been dedicated to reading and to understanding sets of twenty or more programs, which all were supposed to solve the same assignment, but followed different approaches, contained a huge variety of logical errors, etc. Some of these programs were extremely hard to read. Working through them can be both tedious and annoying for teachers and college professors. For companies, however, bad source code can be really expensive. Poorly readable code is a ticking time bomb, in fact.
If you are an experienced professional programmer you probably know that every programmer has his or her personal “handwriting”. You merely have to look at some lines of code and you instantly know who the author was (or wasn’t). In this posting I’m not going to preach a certain “handwriting”. It only concentrates on the most important rules to improve the readability of your code. Programming is similar to speaking a language. A slight accent can make you sound sexy, whereas a strong accent may negatively impact the intelligibility of what you are saying.
1. Choose names wisely!
Always use appropriate names when naming variables, methods, parameters, attributes, constants, classes, and so on. If a variable is used for, say, counting events, name it numberOfEvents rather than n. You will notice that code like this requires far less comments. (Reading comments is time consuming!)
// bad code
int n = 0; /* counts the number of events */
// better code
int numberOfEvents = 0;
Boolean variables may be true or false. If you put is or has in front of the actual variable name (e.g. isEmpty), the name automatically explains that if the value is true.
// bad code
boolean temp; /* true, if bottle is empty */
// better code
boolean isEmpty;
Variables should express the fact that an action is triggered when they are executed. They contain a set of instructions, so they do something. Java Code Conventions, for example, recommend to let the name begin with a verb.
// bad code
public double mean_value( double[] a ) { ...
// better code
public double calculateMeanValue( double[] a ) { ...
Find out if there are any code conventions for your programming language and/or platform and stick to them as close as possible.
Here is an example of what will happen when conventions are ignored: Let’s have a look at the following two lines from a Java program.
A.m1();
a.m2();
If you asked an experienced Java programmer which of the methods is static, he would most probably assume that the correct answer was m1. He might be right in perhaps more than 90% of all Java programs there are in the world. However, if somewhere in the program A is declared to be …
a A = new a();
… his answer is 100% wrong. According to the Sun Java Code Conventions the line above should be
A a = new A();
instead. Not paying attention to upper or lower case is a tiny little sloppiness which could significantly reduce the maintainability of your program.
2. Indent, align, and break the line!
The general idea of indentation is to kind of “visualize” the structure of a program. Classes may contain methods. Methods (or functions) may contain control structures. Control structures may contain nested control structures, … you get the point.
public void m() {
   if( !x ) {
       while( y ) {
// some code
       }
   }
}
When closing an indented block make sure to place the closing bracket exactly at the appropriate level. If you ever had to debug a “} expected” compiler error in an unindented program with more than three nested blocks, you know what I’m talking about.
Proper alignment and use of line breaks not only makes your code look clean and tidy, but it also provides for better readability.
// bad code
double tempResult,speedLimit,positionOfTheSun
,current,variableWithReallyLongName,
someOtherVariable;
int sizeInTerBytes=4,lengthOfText=7,numberOfLines=30;
// better code
double tempResult, speedLimit, positionOfTheSun,
current, variableWithReallyLongName,
someOtherVariable;
int sizeInTeraBytes = 4,
lengthOfText = 7,
numberOfLines = 30
Some companies have very strict code conventions regarding indentation, line breaks, spaces, and so on. Whatever convention you’re following, be consistent!
This particularly applies to the usage of tabs in your program. Do not mix tabs and spaces! This can drive you nuts if you reopen or print your source code file. Be aware, that most IDEs provide tab-based automatic indentation by default. If you accidentally mixed tabs and spaces, check your IDEs preferences and keep an eye out for an option that is called “convert tabs to spaces” or something like that. Some people recommend to generally avoid tabs in source code.
3. Curly Brackets – Not just a matter of taste!
There is one subject among programmers which is like discussing religion. It is the simple question whether this
if( x ) {
   // some code
}
or that
if( x )
{
   // some code
}
placement of curly brackets is better. Some people claim that the second style was easier to understand for beginners. Other people say that the opening bracket belongs to the control statement and therefore should not waste a separate line of code.
Many of my students say it doesn’t matter at all, so they seize the opportunity to try out all kinds of different styles in their final project.
public static void m( boolean x, boolean y ) {
   if( x )
   {
      m1();
   }
   else {
      while( y ) {
          y = m2(); }
   }
}
This of course does not contribute to good source code readability. As to readability it doesn’t matter which style you are using as long as you keep using one style consistently.
If you are not sure which style you should be using for your program, have a look at the source code of the libraries that come with your compiler. Also, you should be aware that if you are using a style that is not commonly used in this particular programming language, you might betray yourself as being unexperienced in that language. A Java programmer who uses the second style from above may be asked: “You don’t do Java very often, right? Looks like you normally do C or something.” So when in Rome, do as the Romans do. 🙂
In case you are interested in more styles that have been invented, check out the following link: http://en.wikipedia.org/wiki/Indent_style
4. Add comments, but add them carefully!
Back in the late 80s I had been taking Pascal programming classes at school. My teacher always said: “There has to be one comment for each line of code!”. I hate to say this about things my teachers said, but this was blatant nonsense.
When you comply with all of the previously discussed rules, you will notice that you won’t need a large number of comments in your program. A comment should always explain why you wrote the code, not what the code does from the computer’s perspective. As this is difficult to explain, I’ll show you an example.
// bad code
int counter = 12; /* assigning 12 to variable
counter */
// better code
int counter = 12; /* the counter will count
downwards starting from 12 */
Always remember that any other person who needs to understand your source code is someone who knows the syntax and semantics of your programming language. So don’t explain the obvious.
What is not directly visible from the code is both the general context (overview) and why the code has been added. Many programmers prefer to write comments before writing the code.
In some programming languages there are even strict conventions on comments. Here is an example from Java which shows you how pedantic these can be.
// bad code
/**
 * This method displays "Hello World!"
 */
public static void helloWorld() { ...
// better code
/**
 * displays "Hello World!"
 */
public static void helloWorld() { ...
Whether you are pedantic or not, you should always be familiar with the conventions that apply to your programming language. By the time when you want to have your own code added to the API of this language you have to be pedantic.
I’d be happy enough if my students followed the most basic rules, which are easy to comply with.
Well, that’s all for today. Have a great weekend!
— Andre M. Maier
Let us now take a look at how functions can return a result. As stated above, the function make_coffee(…) will eventually deliver a hot cup of coffee. Any invocation of make_coffee(…) is going to directly represent the function’s return value at runtime. Thus, a function can return only one single result value upon each invocation. If you want a function to return more than one value, e.g. multiple cups of coffee, at a time, you’ll have to make the return type a container that may contain than one item.
This function is capable of adding two integer values (a and b). It returns the result value directly.
Source Code Readability
Summer holidays ahead, yay! This will be the time when my job is an enviable one. Having spent the last couple of weeks grading never ending piles of final exams and thesis projects I feel like I deserve it. Most of this time has been dedicated to reading and to understanding sets of twenty or more programs, which all were supposed to solve the same assignment, but followed different approaches, contained a huge variety of logical errors, etc. Some of these programs were extremely hard to read. Working through them can be both tedious and annoying for teachers and college professors. For companies, however, bad source code can be really expensive. Poorly readable code is a ticking time bomb, in fact.
If you are an experienced professional programmer you probably know that every programmer has his or her personal “handwriting”. You merely have to look at some lines of code and you instantly know who the author was (or wasn’t). In this posting I’m not going to preach a certain “handwriting”. It only concentrates on the most important rules to improve the readability of your code. Programming is similar to speaking a language. A slight accent can make you sound sexy, whereas a strong accent may negatively impact the intelligibility of what you are saying.
1. Choose names wisely!
Always use appropriate names when naming variables, methods, parameters, attributes, constants, classes, and so on. If a variable is used for, say, counting events, name it numberOfEvents rather than n. You will notice that code like this requires far less comments. (Reading comments is time consuming!)
Boolean variables may be true or false. If you put is or has in front of the actual variable name (e.g. isEmpty), the name automatically explains that if the value is true.
Variables should express the fact that an action is triggered when they are executed. They contain a set of instructions, so they do something. Java Code Conventions, for example, recommend to let the name begin with a verb.
// bad code public double mean_value( double[] a ) { ... // better code public double calculateMeanValue( double[] a ) { ...Find out if there are any code conventions for your programming language and/or platform and stick to them as close as possible.
Here is an example of what will happen when conventions are ignored: Let’s have a look at the following two lines from a Java program.
If you asked an experienced Java programmer which of the methods is static, he would most probably assume that the correct answer was m1. He might be right in perhaps more than 90% of all Java programs there are in the world. However, if somewhere in the program A is declared to be …
… his answer is 100% wrong. According to the Sun Java Code Conventions the line above should be
instead. Not paying attention to upper or lower case is a tiny little sloppiness which could significantly reduce the maintainability of your program.
2. Indent, align, and break the line!
The general idea of indentation is to kind of “visualize” the structure of a program. Classes may contain methods. Methods (or functions) may contain control structures. Control structures may contain nested control structures, … you get the point.
public void m() {    if( !x ) {        while( y ) { // some code        }    } }When closing an indented block make sure to place the closing bracket exactly at the appropriate level. If you ever had to debug a “} expected” compiler error in an unindented program with more than three nested blocks, you know what I’m talking about.
Proper alignment and use of line breaks not only makes your code look clean and tidy, but it also provides for better readability.
// bad code double tempResult,speedLimit,positionOfTheSun ,current,variableWithReallyLongName, someOtherVariable; int sizeInTerBytes=4,lengthOfText=7,numberOfLines=30; // better code double tempResult, speedLimit, positionOfTheSun, current, variableWithReallyLongName, someOtherVariable; int sizeInTeraBytes = 4, lengthOfText = 7, numberOfLines = 30Some companies have very strict code conventions regarding indentation, line breaks, spaces, and so on. Whatever convention you’re following, be consistent!
This particularly applies to the usage of tabs in your program. Do not mix tabs and spaces! This can drive you nuts if you reopen or print your source code file. Be aware, that most IDEs provide tab-based automatic indentation by default. If you accidentally mixed tabs and spaces, check your IDEs preferences and keep an eye out for an option that is called “convert tabs to spaces” or something like that. Some people recommend to generally avoid tabs in source code.
3. Curly Brackets – Not just a matter of taste!
There is one subject among programmers which is like discussing religion. It is the simple question whether this
if( x ) { Â Â Â // some code }or that
if( x ) { Â Â Â // some code }placement of curly brackets is better. Some people claim that the second style was easier to understand for beginners. Other people say that the opening bracket belongs to the control statement and therefore should not waste a separate line of code.
Many of my students say it doesn’t matter at all, so they seize the opportunity to try out all kinds of different styles in their final project.
public static void m( boolean x, boolean y ) { Â Â Â if( x ) Â Â Â { Â Â Â Â Â Â m1(); Â Â Â } Â Â Â else { Â Â Â Â Â Â while( y ) { Â Â Â Â Â Â Â Â Â Â y = m2(); } Â Â Â } }This of course does not contribute to good source code readability. As to readability it doesn’t matter which style you are using as long as you keep using one style consistently.
If you are not sure which style you should be using for your program, have a look at the source code of the libraries that come with your compiler. Also, you should be aware that if you are using a style that is not commonly used in this particular programming language, you might betray yourself as being unexperienced in that language. A Java programmer who uses the second style from above may be asked: “You don’t do Java very often, right? Looks like you normally do C or something.” So when in Rome, do as the Romans do. 🙂
In case you are interested in more styles that have been invented, check out the following link: http://en.wikipedia.org/wiki/Indent_style
4. Add comments, but add them carefully!
Back in the late 80s I had been taking Pascal programming classes at school. My teacher always said: “There has to be one comment for each line of code!”. I hate to say this about things my teachers said, but this was blatant nonsense.
When you comply with all of the previously discussed rules, you will notice that you won’t need a large number of comments in your program. A comment should always explain why you wrote the code, not what the code does from the computer’s perspective. As this is difficult to explain, I’ll show you an example.
// bad code int counter = 12; /* assigning 12 to variable counter */ // better code int counter = 12; /* the counter will count downwards starting from 12 */Always remember that any other person who needs to understand your source code is someone who knows the syntax and semantics of your programming language. So don’t explain the obvious.
What is not directly visible from the code is both the general context (overview) and why the code has been added. Many programmers prefer to write comments before writing the code.
In some programming languages there are even strict conventions on comments. Here is an example from Java which shows you how pedantic these can be.
// bad code /** Â * This method displays "Hello World!" Â */ public static void helloWorld() { ... // better code /** Â * displays "Hello World!" Â */ public static void helloWorld() { ...Whether you are pedantic or not, you should always be familiar with the conventions that apply to your programming language. By the time when you want to have your own code added to the API of this language you have to be pedantic.
I’d be happy enough if my students followed the most basic rules, which are easy to comply with.
Well, that’s all for today. Have a great weekend!
— Andre M. Maier