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 SignatureAll 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.
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 GeneratorsConsider 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 CommentaryWe 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.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.
Create your
podcast in
minutes
It is Free