Derek Bridge - Past Teaching - Software Development

Coding Style

Consider the following 'slogan':

Programming is primarily about communicating with humans, and only secondarily about communicating with machines.

Suppose that a program that you have written is to undergo some maintenance. Or suppose it is to be extended with additional functionality, or ported to another platform or re-used in another software project.

Someone will have to read all or part of your code. This 'someone' might be you. But months or years may have passed since last you looked at this code. Or this 'someone' may be another programmer. And you may no longer be around to give advice about what the program does or how the program works.

If your programs are to be maintainable, extendible, portable and re-usable, they must be readable and understandable.

A good design is one precursor to a readable and understandable program.
A good coding style is another precursor.

The purpose of these StyleFile web pages is to give you ideas about good coding style.

There are general remarks that can be made on this subject.

Consistency

Consistency of style is one of the most important criteria.

People who write on the subject of coding style always have the humility to say that, even if you don't agree with some of the specifics presented, i.e. even if you choose to deviate from their recommendations, you should recognise the importance of being consistent in your coding style.

If you are inconsistent, you can repeatedly wrong-foot the reader of your programs.

Convention

Good coding styles are ones that adhere to conventions. In other words, they are common to, or shared by, a wide community of programmers. Adhering to conventions makes it more likely that others can read your code.

People sometimes casually remark that coding style is a matter of personal taste. That's precisely the opposite of what coding style is about. Personal idiosyncracies subvert the goal of understandable software.

Well-run projects and well-run software engineering organisations agree and impose a coding style; they stamp out personal idiosyncracies.

The argument that such conventions stifle creativity is rot. Working within constraints is typically a harder and more creative task than working free of constraints. And programmers have plenty of other opportunities to exercise their creative skills in arenas other than bewildering program layout and confusing variable names.

The programs you write for this course will be judged against the coding style criteria that are set out in these StyleFile web pages. Read and take note!

Identifiers
Advice about the way you name entities in your programs: a prime determinant of your program's readability.

Variables & constants
Advice about the declaration, initialisation, identifier scope, lifetime & visibility of your variables.

Layout
Advice about the formatting of your code so that its logical structure is apparent.

Comments
Advice about what makes a good comment: why should you write them, what should you write, how should you write them, when should you write them and where should you put them?

Acknowledgments