HOME BUILDER
JAMES HEIN
Do you know COBOL? Newer programmers will know Visual Basic, C#, C++ and perhaps Pascal, but Common Business-Oriented Language (COBOL) has been around for a long time and still makes up some very large systems.
Consider the state payroll system in California, it is COBOL-based. A recent request to make changes to this ageing system to cut costs was thwarted because among the people to be laid off were the remaining COBOL programmers.
If you think that COBOL is on the way out, then consider that there is still an estimated 180 billion lines of COBOL code still running the world's businesses and a further five billion lines are added every year. There are still many versions around, including a .NET version I found a while back.
The lesson here is that any code you write today could be still going in 50 years, so it is worth spending some time on documentation.
Documentation is one of those areas that is typically ignored or poorly done. I have worked for company after company that has either no or poor documentation of their programs. When I started out in computing it was as a maintenance programmer, and after a couple of years of that I vowed to leave a trail of documentation wherever I programmed. You can start with in-code comments. I have lost count of the number of times I have heard that a particular language or system was "self documenting." This is rubbish, and is usually said by managers, sales people and marketers who have never written a line of code in their lives.
The object-oriented approach has helped the world with this because at least you know what pieces of code are used by what objects because it tells you. If a procedure is used by multiple objects in say a C# .NET application the subroutine keeps track of what is calling it. The procedure name also often helps; submit - onclick is somewhat of a giveaway when you are trying to work out what this procedure is for. Once you get outside of the automated and generated procedure world however, things change.
A function called Processresults might make sense to the person who wrote it, but what results and how are they being processed? A single line at the top - something like "processes returned sales figures and normalises for state results using a three month moving
average" - can save a lot of head scratching. A name change to processsalesfiguresresults
is also a good place to start. If you have a tricky, or as we know it interesting, solution, then short pseudo code comments can lay out the logic of, say, a function. These can be added as you code, so it takes a very short time and is not forgotten days later. I have seen some brilliant code that took me a long time to work out because it used rarely considered elements of the Windows API, for example.
The larger the application the more documentation is needed. Start with an overview diagram of where the inputs come from and where the outputs go. As I read that last sentence I am reminded that I am a data-focused person. I like to break systems down into their basic data components and then build code that links the data together. The other half of this are the processes, which are just as important. How does the data come in, get processed and go out? Is XML or Web Services required, or is this a simple database query? In any documentation the process and data documentation compliment each other, so remember to diagram and describe the processes along with the database structure.
"Why" is also an important consideration when you document. I have sometimes looked at code and wondered why it was done that way. Sometime there were historical reasons or business rules that drove and drive coding that are not always obvious when you look at code. It doesn't help when you have finished rewriting something to find out that some obscure business rule means your changes will not work or be used.
Finally think about the person who will be maintaining or modifying your code. Ask yourself this question and document accordingly: "Will the next person understand what I have done here?" Hint the answer is often "No."
Email: jclhein@gmail.com.
Prev
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Next
