Maintainability: Worked example

Rather than just stating the techniques, we thought it would be better if you followed a worked example of real code.

Let's imagine that you have just joined a new company as a programmer and the first thing they do is ask you to alter some source code that a previous employee has written.

The computer language used is PHP but that does not matter, as the same approach should be used whether you are writing in Python, Java, Assembly language or anything else.

We begin with source code that has been deliberately made to be as horrible as possible in terms of maintainability.

Look at this code:

The link below will show the code in a new tab in your browser, we recommend you drag that tab out of the browser to create a new view so you can see it side by side with this page.

Please open this link IN A NEW WINDOW to view the code

Question: With just a brief view of the code, can you tell what this code is supposed to do?

Answer: Very unlikely, even if you were expert in PHP. The programmer has given no explanations or structure, making it very difficult to follow. But it is perfectly working code! Which means you can write functional code, but it takes skill and professionalism to make it maintainable. We shall build up this code to show how this is done.

Solution: The original programmer should have included a header comment stating its purpose.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

Can you spot the header? It's in line 2.

Now the code tells the reader the bare minimum of information - that this program is an RSS reader. RSS is a web technology to send news to its subscribers, so this code is intended to read a RSS newsfeed.

But it's still rather bare.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

From line 3 and on, the header has now been expanded to include several new details. It now mentions the original author of the code, the date that the program was written and the version number.

This is much more useful.

As we discussed on earlier pages, one of the key tools to making source code readable is formatting and whitespace. The human eye is drawn to patterns, and blocks of text broken by empty lines intuitively indicate that different things are being discussed in each block.

The php code we've been looking at so far is completely unformatted. Let's see what it looks like with just some simple line breaks:

Look at this code:

Please open this link IN A NEW WINDOW to view the code

In this version, the programmer has added blank lines (lines 10, 15, 21, 38) to provide some visual space between code blocks.

Now it is apparent where the FOR, IF, and FUNCTION blocks begin and end. This improves readability dramatically, but it could be improved even further.

Functions (subroutines \ procedures) are self-contained blocks of code that are called from other parts of the program. It is very useful to easily see where it starts and ends, because you can see if the function syntax is correct (in PHP it needs to start and end with {}). The return value - if any - is also easily visible.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

As you can see, everything inside the function is now indented to illustrate the relationship of those lines of code.

The opening { bracket on line 11 clearly has the correct } closing bracket on line 40 according to the syntax rules of php. The return item on line 39 is also obvious. All this from a single indent of the code.

There's still more to indent, though!

Look at this code:

Please open this link IN A NEW WINDOW to view the code

Now the conditional statements and loops (IF and FOR respectively) within the function are also indented to indicate where they start and end.

Now that we've formatted the code and separated all of the blocks of code by their purpose, it's time to make it clearer what those purposes are. This is where commenting comes in handy. To mark a section of code as a comment in this language, you use the characters // (it is different in other computer languages but they all have a way to comment code)

Anything after // on that line will be ignored by the computer when it comes time to run or compile the program.

The first thing to comment on is the purpose of the functions. A program often has many functions - dozens is not unusual. The programmer should explain what each function is intended for. The description should be in clear language and be fairly non-technical if possible.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

In this case line 11 to 15 explains the function and how it is to be used.

Next up, changing the names of the functions and variables to be more descriptive. The programmer might have known what the function "f" meant (lines 8,16), and what the variables "a" (lines 22,27) and "c" (lines 9,17,19) were, but we certainly don't!

Using descriptive names makes it much easier to locate where else in the code that function or variable is mentioned. And also what is the purpose of the item.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

As you can see, function "f" ( line 16) is now named "getRSSdetails", since that's what it's doing - it is getting RSS details from a database. All references to the function in the source code have also been updated (line 8)

The variable "a" (line 22) is now "num_results", since it's showing the number of results and this is used in the for loop as well on line 27.

And the variable "c" is now "db" - short for "database". So the instruction on line 9

$db->disconnect

should be pretty obvious that a database is being disconnected.

You could be even more descriptive than this with your naming scheme, but at some point it becomes tedious to type out long names.

The last stage is to add general comments throughout the code, just to make things easier to follow.

Look at this code:

Please open this link IN A NEW WINDOW to view the code

Now it is time to add even more comments. But intelligent ones!

If you were a professional programmer, imagine that your source code was up for review on a big projector screen (not unusual in a real company doing a code review!) with lots of your fellow programmers in the audience - what would you say about your code as you walk through it?

This is what your comments should contain - not minor technical detail such as 'this increments a variable', but your thinking behind an item or block of code if it is significant.

As an example, line 21 says

if (msql_affected_rows() > 0 ) { // deal with no records being returned

The comment 'deal with no records being returned' has nothing to do with the actual line of code, it is assumed that the reader is familiar with php and knows what the code instruction itself means, but the comment is saying what the programmer was intending this code to do. This really helps with spotting logical errors if that bit of code does not do what the comment is saying it should.

If you were unfamiliar with the programming language - php or anything else - look at the comments. It is as if the programmer (John Brown in the header) is guiding you in his thinking as the code was written. Good comments should not matter about the actual code being used.

Now that we're done making this code more maintainable, it's worth comparing it to what we started out with. The two styles of coding are shown side by side. They do exactly the same thing, the computer does not care about comments, indenting, formatting - but you or your fellow programmers will!

Please CLICK HERE to view the code

Hopefully, you will appreciate that the code on the right is going to be far easier to maintain than the obscure code on the left.

For example, if the code had to be re-written in Java rather than PHP, it would not be too hard a job if good coding practice has been used.