In any serious application, the importance of documenting your work can't be overemphasized. Its nearly a certainty that you will need to return to the code later to correct a problem, integrate a new feature, or tune for performance. If you're unable to determine what you were doing without reading the code line by line, you'll not only waste a tremendous amount of time, but may misinterpret the original intent and cause additional errors to be introduced.
While you cannot use commenting and documentation as a substitute for an understanding of the source code, a well documented program will be easier to modify, debug, and maintain.
There are almost as many different opinions on what makes for good commenting and documentation as there are programmers, so I won't claim to have a definitive set of rules for documentation, but I can say that this has worked well for me. Feel free to define your own standards for documentation. What's more important than following any particular standard is to set a standard and follow it faithfully.
I've broken down my documentation standards into three basic areas:
- Application Design Documentation
- Source Code Documentation
- End-user Documentation
Application Design Documentation
Depending on the size of the application, this may be a few short pages describing the goals and overall design of the application, or may be a long series of formal documents. You may keep permanent bound copies filed with the rest of the documentation for the application, or just use it as a tool to organize your thoughts.
Whatever approach you take, its important to sit down before you start coding to plan out what it is you want to do and how you want to do it. You wouldn't take off on a trip accross the country without an idea of why you're going or how to get there. You shouldn't just sit down and start coding either. Here's a few things I like to do at this stage.
- Give the application a name.
Even if its just an informal code name for the project, it helps to bring the project to life.
- State the goal of the application.
Forget design and implementation at this point. Decide what the application is supposed to do and how having this kind of tool will help the overall objectives of yourself or the intended users. Its often helpful to use a problem and solution approach - state the problem that the intended users are having and how the application would be a solution to the problem.
- Describe the features of the application.
Provide a list of the features the application will support and how the features will be integrated into the final product.
- Develop a design strategy.
Break down the major components of the application design, describing how each will be implemented into the application and integrated with the other components.
This is a very informal list. On a large application, you may have detailed requirements documents, change control procedures, and so on. For a small application, this may or may not be necessary - you'll have to make your own choices based on your needs and the needs of the customer. If you're writing a little utility for personal use, a page or two may do the job. Large applications may have hundreds or even thousands of pages of documentation written before one line of code is entered.
Once again, what's important is that the documentation is appropriate to the project and that you do take some time, even for small projects, to think through why and how you will reach your objective.
Source Code Documentation
Programmers have widely varying opinions on writing source code comments. Some say they are a waste of time, or can even be harmful if they are not done correctly. Others say that no application is complete without good commenting in the source code. Some will even impose rules such as one line of comments for every five lines of code. I won't suggest any such rules for you. The level of comments you find useful may be dramatically different from what I find useful. One thing to keep in mind, however, is that for any serious application, its likely that eventually someone other than you will need to read and understand the code. Even if you're the only programmer in a five person company, you may one day leave the job and need to be replaced. If the next person who reads the code can't understand it, chances are they won't think of you as a mystical coding genius, but rather as a lazy bum who didn't finish his work.
Here's a few things that I find helpful in writing source code comments:
- Create a block comment for each module.
Describe the purpose of the module, the use of module level data, major procedures, and major interfaces to other modules.
- Create a block header for each procedure.
At the top of each procedure, create a short (one or two lines should suffice) comment describing the purpose of the procedure. I also find it helpful to describe the purpose of any parameters used by the procedure in this area.
- Sketch out a procedure with comments before you write it.
Write comments indicating each step in a procedure, telling why the step is taken and describing the logic of the code. Once this point is reached, you can simply fill in the code between the lines of comments to complete the task.
- Describe the use of data declarations.
If you are declaring variables and the purpose of the variable isn't obvious, write a comment describing the purpose of the variable.
- Use comments to describe the the intent of the code.
A decent programmer should be able to figure out the details of the code by reading it. Its more useful to have your comments describe what the code is supposed to do than to describe how it is done. This also makes the comments easier to maintain because you can change the implementation without rewriting the comments.
- Don't use comments as an excuse for poor code.
If you are writing elaborate comments because part of the code is "tricky", consider rewriting the code to be straightfoward rather than documenting the "trick". While there are times when you need to employ a shortcut in the code for the sake of efficiency, in most cases you'll be better off in the long run to leave out the shortcut and write the code so that you can come back later and figure out what you did.
There's nothing more frustrating for a user than to be sitting in front of an application and not know how to accomplish a task that the application is capable of doing. While it is an admirable goal to have an application with a user interface that's so well designed that no one ever needs to consult the manual or help file, it probably isn't possible. What's obvious or intuitive to you may be cryptic to the next person to use the program.
The key point to remember when you are writing end-user documentation is to write the documentation at the level of understanding of the people who will use the software. In most cases, this will not be programmers or even power users, but normal people who use the computer as tool to accomplish a task.
Here's a few things to keep in mind when writing help files and manuals:
- Describe the overall organization of the program.
New users in particular often need to get a "birds-eye" view of a piece of software in order to understand where to start. Provide an introduction to the program where you describe its capabilities and major features and how they can be used to complete an objective of the user.
- Tell how to use the program, not how it works.
The end user doesn't care if the program has 10 lines of code or 10 million. They just want to get their work done. Don't give your users a programming lession - teach them how to do what they want to do.
- Provide a decent table of contents and an index.
Once most users become familiar with the program, they will use the manuals and help files mainly as a reference. Make their life easier by making the information they need easy to find. Although you can now do full text searches on help files if you are using Windows 95 or Windows NT, that's no substitute for a well done index.
- Cross-reference appropriately.
No part of your application exists in a vacuum. Provide links in help files and written documentation to other relevant topics.
- Provide a means to obtain further assistance.
Even the most expert user working with the most complete help files and manuals may occasionally get stuck on a problem or not understand a feature. While you may not have the resources to provide a tech-support phone number, you should at least have available an e-mail or web address where users can go if they can't figure out a problem or need to report an error in the application.
Clearly, there's a lot more to writing good documentation than this. You may wish to start by reading the introductory chapters of the Help Compiler Guide
, which will give you some excellent ideas about creating well written and well organized help files, and the The Windows Interface Guidelines for Software Design
. Both of these will give you a good start toward creating well designed and useful documentation.
Originally written by Joe Garrick