Fat Agnus

This might be somewhat controversial since everybody has there own opinion on how one should write code. Everybody likes there own way of writing code and this might be ok, if you are the only one who will ever work on it, but if you are a part of a team, then it is very important to now how to write code that everybody can understand without using to much time to figure out what a function, class or something else does.

This guide might only be beneficial for people who are beginners and are open minded about learning a few guidelines on how to improve their programming skills. I won`t go into the deeper aspect of programming because then I will end up writing a book and there has already been written too many books about that.

For the course of simplicity in my examples I will use Php as programming language.

How to write High-Quality functions

What is a high quality function? That`s a good question so let`s look at a function which has been considered as a low quality function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

function DoSomething( $a, $user, $color, 
$total, $type, $time, $date, $street, 
$coordX, $coordY )
{
	$newtotal = $total * 1.25 / 30;
	UpdateProfit($newtotal);
 
	$n = 100;	
	for($i = 0; $i < 10){
		if( $a == 10 )
			UpdateUser($user);			
			NewColor($color[$i]);			
			}
			if( $a == $n )
				NewColor($color[100]);
			}

Can you see what is wrong with this function? Try to think about what could be wrong and why it is wrong before you continue.

• The functions name (DoSomething()) doesn`t give you a single clue on what it is doing.
• The function isn`t documented.
• The function is poorly formatted. It is hard to se what belongs to what.
• The function contains some strange numbers like; 1.25, 10, 30 etc.
• The function has too many parameters. To keep it understandable, it must contain around 7 or less.
• It seems that the function does more then one thing.

Pseudocode

The purpose of using pseudocode (more about pseudocode) might seem trivial to some (especially if you are an expert programmer) but it is an excellent technique you can use when you need to get a mental orientation of what your function is going to do. Once you have written your pseudocode then back away for a moment and think of what you have just written; does the code make sense? You could also try to explain what the function is going to do and have someone review your pseudocode. When you are ready to write the actual code, you don`t necessarily have to remove the pseudocode, it can be great as documentation for what the function does.

Good routine names

This might sound easy enough, but even though you understand what the function does (because you wrote it) it doesn`t mean that everyone else will understand it, and so they will have to look through the code to figure it out. A good function name clearly describes what the function does, and don`t be shy to make it as long as necessary.

Routines tend to be more complicated then variables, and good names for them tend to be longer. On the other hand, routine names are often attached to a object name, which essentially provides part of the name for free.

- Steve McConnell

Defensive programming

It may sound like a strange term but it basically means that you should take responsibility for your code and not let anyone mess with it. Protect your code from invalid, bad and corrupted data because then you accept that programs are being modified all the time.

Localize variables

Don`t declare any variables in the beginning of your code, if you first are going to use them in the end. If you keep the variables as close to the code that are using them, it enhances the readability of your code and thereby the understanding as well.

Variables

Use each variable for only one purpose, I have seen many use the same variables for different things and that will give you a serious headache when you need to debug your code. You should also remember to give your variables meaning full names and don`t leave unused variables in your code.

Research shows that the optimum average length for a variable name is 9 – 15 characters.

- Steve McConnell

Learn more from Code Complete