1. Documentation
It contained inside the code itself. It consists of
- clear layout
- good routine names
- use of named constants
- descriptive variable names
- minimal control flow and data structure complexity
Layout:
Good Layout includes use of white space and effective use of spacing to make it easy to see the repetitions statements and selection statements of the program.
Routines:
Require effective names. Names that say what the routines do. Make sure that they are used for only one purpose. For example Find, List, and Delete.
Constants:
Also require effective names: They should describe what the constant is used for. Use constants instead of “magic” numbers.
Ex Define Ten = 10;
Variables:
Make sure that variable names distinguish global, local, enumerated types, and constants. They should also like routines only do one task or be used for just one function. Don’t have “garbage” or “DoStuff” or “FooballRules” variable names.
Selection Statements:
Should have the normal case follow the IF expression instead of the else. Try to avoid as much as possible nested if statements. Try to make them read like English sentences. For example:
Control Statements:
Try to make them simple and have the loop control variables more descriptive then x, y or z. For example:
Like Selection Statements you should try to keep nesting of loop to a minimum.
Following these standards should naturally minimize the amount of comments that you have to implement.
The necessity of comments is a hotly debated topic but it is widely accepted that they should be used in a number of levels.
They can be stored as separate files describing what particular routines or modules do. They should also be inside the code.
This is the lowest level that comments exist. They should be reserved for the tricky parts of your code and keep to a minimal because too
much comments takes away from the readability of your code. While at the begging of each of your files you should include the PDL of your code.
Here are examples of bad and good routines.
2. Comments
Keys to Effective Comments
1.Should we use comments?
If we don’t do it well, it wastes your time and it wastes the time of anyone who tries to understand your code. But if its done well it makes the program a lot of easier to understand.
2.Commenting Efficiently
Effective commenting isn’t that time-consuming. Comments can take a lot of time to write for two common reasons. First, the commenting style might be time-consuming or tedious-a pain in the neck. Second, commenting might be difficult because the words to describe what the program is doing don’t come easily. The time you spend “commenting” is really time spent understanding the program better, which is time that needs to be spend regardless of whether you comment
- Use styles that don’t break down for discourage modification.
Any style that’s too fancy is annoying to maintain.
- Use the PDL-to-code process to reduce commenting time.
If you outline the code in comments before you write it, you win in several ways.
- Comments as you go along.
The alternative to commenting as you go along, leaving commenting until the end of the project, has too many disadvantages. It becomes a task in its own right, which makes it seem like more work than when it’s done a little bit at a time.
- Here are examples of bad and good routines.
Commenting Techniques
Good Comments should say things about the code that the code can’t say about itself. Good code is its own best documentation. Commenting is amenable to several different techniques depending on the level to which the comments apply: program, file, routine, paragraph, or individual
General good commenting technique
- Like PDL, comments are written in terms of code’s intent or summarize what the code does, rather than just repeating the code.
- They are explain the “tricky bits” (hard parts).
- They can be useful as “TODO” markers.
- Use the PDL-to-code technique can reduce commenting time.
- Add comments as you code or before you code, NEVER after.
- One of the very useful functions that can be served by comment, is as a “changeLeg”.
Things that should be documented in comments
- Things that aren’t obvious from the code.
Particularly, programs involved in “ inter-process” communication.
- Things that get around system errors or make use of undocumented or little known features.
If it’s an error, it’s probably not documented.
- Parameters to Routines
- IN / OUT / BOTH
- Allowable ranges / values
- Limitation on a routines capabilities
- Global Data
- Every time we use it
- Its declaration
- What the various branches of an “if-else if ” or ‘case’ statement are for
- Each control statement is commented
- The ends of long or complex control structures are commented.
- Change / Revision History
- Each group of lines that get modified in a change / revision should be commented as part of the “ChangeLeg” Item.
- What a module / class we need a description of its purpose, and summary of the routines in it
Particularly, the public interface
- Here is an example of good routines.
Author: Brien Beattie, Dean Vargo, Yixiang Wang, Yawen Wu, Hong Zhang
Date : June 19, 2000.
Copyright:
Department of Computer Science, University of Regina.
[CS Dept Home Page]
