It is hard to think of a facet of software development that programmers dislike more than documentation. This task is almost always pushed to the end, and shortcuts are used wherever possible. However, we also are quick to complain about a lack of documentation when we pick up others’ code. Maybe we need to give so we can get. that is the focus of this episode.
Documentation Begins With A Signature
All good documents start from an outline. There is either a written or mental plan that the author follows. In software, this objective comes from the signatures of the class and methods. We have a set of details we must provide for every method out there.
- What are the parameters supported?
- Are there constraints for those parameters?
- What is returned?
- Are there exceptions or error-handling that needs to be documented?
- Do we require other classes or libraries?
- Are there side effects?
That is a sizable list when you consider that many methods are documented in a sentence or two. While documentation can be exact and concise, that is not always best.
Using Documentation Generators
Consider a method:
integer DoSomething(parm1, parm2)
Here is the typical documentation:
DoSomething returns an error code or 0 on success. The first parameter is a number that tells which type of processing is needed (trim, pad, compress, encrypt). The second is a string that is processed.
I am being a bit obtuse in the above comment, but not far from what most automated tools generate. That should be a start for our documentation and not the final version.
Add Color Commentary
We need to add details and specifics to our documentation. This includes things like validations, side effects, and avoiding magic numbers. Therefore, a better approach to the above would be something like this.
DoSomething returns a 0 for success, -1 if the action is invalid, -2 if the string is null, -3 if the action fails. The first parameter (parm1) is an integer with a value of 0 to 3. This tells the method the action to perform.
-
0 - trim the string
-
1 - pad the string (left pad spaces to make the length 20)
-
2 - compress the string
-
3 - encrypt the string
The second parameter (parm2) is the string the action is performed on. The resulting string is set in the instance and can be viewed through the getValue method (provide a link to that method if possible).
There is minimal formatting in the example above. Nevertheless, notice how much more information we have now provided. There is no guesswork, and our expectations are properly set. Thus, we have a document that is useful and will make the next developer happy to work with our code.
