Writing Source Code

Here is some basic advice on writing source code for your programs.

Split any Significant Program Into Modules

A single source file shouldn't be too long. I generally find that one or two thousand lines is the upper limit. Bascially the idea is that you should be able to split any significant program into bite-sized chunks of related functions. If a program is split up into appropriate modules you will find that you don't have to search through reams of unrelated code for the piece you want to edit, and you also won't have to jump around between half a dozen or more source files when working on a single problem. For C++ programs an effective strategy is often to put each class (or related set of small classes) in it's own file. For C programs one generally puts sets of closely related functions in a single file.

Use a Consistent and Clear Style

Place braces, "{" and "}", clearly, and indent appropriately to represent the nesting of loops, if and else clauses, switches and other such statements. Source code which uses a consistent style is much easier to read, and if you write programs that anybody actually uses you will end up reading the code at some point and wondering what you were thinking when you wrote it.

Name Functions, Classes and Variables Clearly

When you look at the name of a function, class or variable it should be clear

  1. What the purpose of the item is (e.g. ReadBitmapFile, fileToRead, cBitmap)
  2. What type of item it is (a function, a class, or a variable and what type of variable)

When I say clear I mean clear within some basic framework. It would be silly, though not unheard of, to label each item like "function_ReadBitmapFile", "variable_file_handle_FileToRead", "class_Bitmap" and so on. However, using consistant abbreviations and conventions to do the same thing is a good idea. Thus a name beginning with a capitol letter is a function, a name prefixed with 'c' is a class, and variables are prefixed with a lower-case abbreviation representing their type (like n for integer, d for double, sz for C-style string, str for C++ string objects, and so on) in much of the code I write.

Don't give in to the temptation to save typing by over-abbreviation. When you look at code six months later it really is easier to understand "GetWindowHandle (nListIndex)" rather than "gwhn(n)". Of course, don't go completely overboard with long names either ("GetWindowHandleAtGivenIndexInList (nListIndex)" is generally redundant).

Use Comments

Not only do comments help you understand the code you wrote when you read it again, they also help you organize yourself while you are writing code. By writing comments at the beginning of if else clauses or switch cases explaining what you intend to do but filling in the actual code later you can quickly lay down the fundamental structure of a piece of code and evaluate for yourself whether an idea works when translated into code. However, avoid using meaningless comments like:

	nErr = ERROR_NO_MEMORY;	/* Set error value to no memory error. */

or

	for (x = 1; x < 10; ++x)	/* Loop from 1 to 9 */

Anyone who knows enough about C programming to think about editing code should be able to understand the code at the level written in those comments without reading the comments themselves. Comments should explain why the memory error value is set (if it wasn't explained already) and why there is a loop from 1 to 9 (particularly, why 1 and why 9) and what it does.

Be Consistent

I said something like that above, but it can't be said enough. All 'rules' of programming are matters of taste. Some people prefer larger modules and some prefer smaller. Some people comment almost every line, some write large blocks of explanation (my style), and some write only terse comments on particularly obscure points. There are various religions... er... schools of thought concerning where the opening brace should be placed after a while statement, and whether functions should be named like "get_next_handle" or "GetNextHandle" and so on. What is important is not really which style you choose, but that it is clear to you and you use it consistently.