Next page | Contents page |

Some programming principles

The biggest temptation when starting a new program is to dive in and starting writing code. Even professionals find it hard to stop themselves doing that.

Instead you should first make sure you have a complete list of requirements. Write them down.

One big advantage of doing that is that you will be able to tell when you have finished coding. Otherwise you might go on adding frills for ever.

A list of requirements forms the basis for a list of tests that can be done to determine whether the program does what was required.

If someone has asked you to write the program the requirements may provide the basis of a contract. At the very least they enable you to demonstrate that you have done what was asked. And that other person can verify for themselves (this is called User Acceptance Testing, UAT).

There is an established method of programming called Test-Driven Development (TDD). It says to write tests in the form of program code for each of the requirements. For each test you must first see it failing and then write code to make it pass. Seeing it fail is vital because then you can be sure that the code you write is necessary.

Having said all that, it must be admitted that one of the biggest problems in programming is due to the mismatch between spoken languages and programming languages. How can we be sure that the requirements are completely unambiguous and that we have interpreted them correctly, even when writing the tests?

When writing the code do not be tempted to use clever constructions. The golden rule is: KEEP IT SIMPLE*. Otherwise when you come to modify the code or fix a problem in it, some months or even years later, even clever old you will forget how the trickery worked. Keep it as simple as possible and lay it out as clearly as possible.

As has been mentioned in a side box, comments can be useful. If you do something out of the ordinary do write comments explaining how and why. DO NOT write comments that merely say what the code is doing: the code already embodies the truth about that and any comment may be subtly different, wasting a maintainer's time.

It may seem a small and pedantic point but do pay attention to spelling and grammar in comments. Anyone looking at the source code (which they always can in JavaScript) will lose confidence in the whole thing if the comments are sloppy. They will assume the code must be sloppy too. Presentation is very important, to give people confidence in the quality of your work.

* The golden rule of software development always used to be abbreviated as KISS, meaning "Keep It Simple, Stupid". I have not heard it for many years. Is that because the virtues of aiming for simplicity have been forgotten or just that it is too offensive, implying that someone is stupid?

Next page | Contents page |