Software documentation is all about bringing clarity into a code baseline. It provides clues to clarify the meaning of certain code structures. For this purpose, we use best programming practices and tools to clarify our software.?When documenting software, we aim to minimize time spent hunting for meaning. We want anyone using or reading our code to know exactly what we meant when we wrote it. In addition, they should also know how to use our code without having to look for extra clues. Whether it’s an API, a suite of REST services, or simply a method in your code, it should all be clear.? When things are not clear, you have to dig up the meaning from other parts of the code, and this is a waste of time.
In this article, we’ll explore what information to document and how to do it. Lastly, we will talk about presenting our software documentation.
Document Your Code
When determining what to comment on in your code, it’s good to keep maintenance programmers in mind. What would other programmers need to know in order to understand and use your code properly? Is there anything surprising in your logic? Is there anything outside of the code that would be helpful?
In general, we find three main coding structures in most programming languages?variables, methods, and classes. As developers, we target these three structures for providing clear comments. Best coding practices require comments only after exhausting all possibilities for using meaningful names in your code. Any hidden or surprising meaning should be documented through comments.
You must also provide comments anytime you sell code to external users. Selling APIs or web services requires clear and formal documentation. Let’s take a look at documenting your APIs.
Document Your APIs
Application programming interface (API) is a term used to describe the entry points to a particular software module. An API contains method calls that require certain parameters and can output certain results. APIs, in general, provide a logical grouping of methods. This interaction between input and output must be captured in clear and concise documentation.
For example, anytime you use an ArrayList in Java you use the ArrayList API. As a developer, you don’t particularly care how the internals of the ArrayList work, because you only use this data structure. The Java ArrayList API tells you clearly what methods you have available for this particular object and how to actually use these methods. You read about what type of inputs to provide and what outputs to expect. Clear API documentation must achieve just that?tell users how to use the API without having them look at implementation details to find out.
If your company is selling software modules with APIs that plug into your customers’ systems, then documenting your APIs is absolutely necessary. Even if everyone using your code module is from your own company, documenting APIs is usually good coding practice. Any point that provides an interface between one module and another module is a great candidate for software documentation.
Your company might also sell or give access to a suite of REST services to your customers. Services expose your system’s functionality to your users. A REST API also requires clear documentation because your users should only be concerned about how to properly use your REST services and not how you’ve built them. When users cannot understand how to use an API (be it REST or code API) and start asking questions about implementation, then your software documentation must be lacking.
Now that we talked about what to document, let’s turn our attention to how to do software documentation in your code.
One-Line Comments
The simplest comment is a one-line comment. You simply add the characters // and whatever comes after is ignored by a compiler or interpreter. You can place these characters at the beginning or end of a line of code.
A one-line comment looks like this:
//My amazingVariable does amazing things. int amazingVariable;
Another variant of a one-line comment can start at the end of your comment line like this:
int amazingVariable; //my amazing variable.
The best practice, however, is to use a one-line comment on its own line instead of at the end of the line. This makes the code easier to read and avoids having to scroll to the right in order to read an end-of-the-line comment.
We should use one-line comments to provide a clue about something unexpected or outside the system. Short and to the point.
Multi-Line Comments
When explaining my code requires more space, I use multi-line comments. This is simply a comment block that takes multiple lines. In order to avoid using // for each comment line we use a comment block sign /* to start and */ to end the comment block. A multi-line comment block looks something like this:
/* * This is my multi line comment. * It uses more than one line to explain more complex concepts. */
While they’re very easy to do, multi-line comments should raise a red flag in your mind. Do you really need this many words to explain your code? Can you refactor your code so that variable and method names communicate their function better without using comments? Most of the time, refactoring makes your code cleaner and clearer without the use of comments. However, if there’s a lot of business logic outside of your code, using a multi-line comment block can bring clarity for everyone. If you need it, then use it.
Variable Comments
I only bring up commenting variables for the sake of completeness. However, in daily practice, we shouldn’t have to comment our variables. If your variable needs a comment, you probably need to change the variable name so it becomes a meaningful name. If you have to comment your variable, a one-line comment placed above the variable definition is usually the best practice.
//My amazingVariable does amazing things. int amazingVariable;
Method-Level Comments
Moving on, we’ll talk about providing comments for our method definitions. Again, choosing a clear method name can replace method comments and result in clearer code. If, however, your company decides to add formal method level comments, they will look something like this (in Java for example):
/**
* Returns the character at the specified index. An index
* ranges from <code>0</code> to <code>length() - 1</code>.
*
* @param index the index of the desired character.
* @return the desired character.
* @exception StringIndexOutOfRangeException
* if the index is not in the range <code>0</code>
* to <code>length()-1</code>.
* @see java.lang.Character#charValue()
*/
public char charAt(int index) {
...
}
Using formal documentation tags (like @param and @return) will help you generate formal documentation which you can easily present in a web document (keep reading for more discussion later).
Class-Level Comments
If you’re using an object-oriented language, creating a class container will give you the opportunity to create class-level comments. Whether you create them or not really depends on the level of formality required by your company or customer. In any case, a class-level comment for a Java class can be as simple as a multi-line comment block placed right above the class definition. On the other hand, in order to be picked up by the JavaDoc documentation generation tool, a formal class-level documentation should look like this:
/**
* A class representing a window on the screen.
* For example:
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.15, 13 Dec 2006
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}
If you decide to use formal comment formatting, your company needs to create a standard for all developers to use. Using uniform documentation formatting results in a uniform help document, when generated by the tool of your choice. This is especially important when you’re selling a product that includes APIs. A formal documentation process is crucial in this case.
Use Your Tools to Manage Comments
Most modern integrated development environments (IDEs) provide a quick way for creating comments in your code. Typing /** followed by the Enter key, will create a multi-line comment block automatically for you. It’ll look something like this:
/** * Just fill-in your comments and when you press ENTER, a new comment line * preceded by the correct * symbol will be created. This way you can focus on * creating clear and concise comments. */
All you have to do next is add your clear comments, and your IDE will take care of adding the proper comment syntax.
Also, creating method-level comments is easy when using an IDE. Let’s say I use InteliJ,?and I write a simple method definition like this:
public double computeWeeklyOvertimeHours (double totalWeeklyHours, String countryName) {
// method logic
}
Now, I want to create standard Java method-level comments. It’s pretty simple! All I have to do is position my cursor right above the method definition and type the /** symbol and press ENTER. This way, the IDE knows exactly what I want to do. Consequently, InteliJ generates the following comment block:
/**
* I can enter comments here describing this method.
* @param totalWeeklyHours
* @param countryName
* @return
*/
public double computeWeeklyOvertimeHours (double totalWeeklyHours, String countryName) {
// method logic
}
As you can see, the IDE picked up the method parameters and added the @param tag. It also added the?@return tag that you can simply fill in for describing your output. Using your IDE to generate method-level comments is a time-saver, especially when you have to document large APIs using standard tags.
Do you have to use all these standard tags in your documentation? You don’t, but it’s normally a good practice to follow, especially if you have external users for your APIs. In order to present your software documentation in a consistent and formal way, using standard tags will allow you to use documentation generation tools for beautiful presentation.
Presenting Your Software Documentation
When it comes to documentation, it’s generally required for any APIs, especially externally facing ones. When other companies use your API, you must have clear documentation.
For a Java codebase, using JavaDoc is the default way of creating and publishing API documentation. The Java API document is a clear example of what output JavaDoc creates. Once you’ve created code-level comments using the specified documentation tag, a simple run of the Java documentation tool will create a functional web document that can be part of your customer deliveries along with your API and binaries.
GhostDoc, on the other hand, uses XML tags in the codebase to generate documentation. Provided that you created the required documentation tags in your code, you can also create a web document to include with your code deliveries.
Swagger UI?provides custom tags and documentation generation tools for presenting REST API documentation.
Using a tool for generating software documentation forces you to learn and use some predefined tags, but you’ll always produce consistent documentation that’ll provide great value for your users.
Good Software Documentation Shows Care
We’ve talked at length about what we have to document and how to do it. Whether it’s your customers or fellow programmers who use your code, having clear software documentation shows you care. Doing software documentation the right way goes a long way in establishing your professionalism. When users of your software find good documentation, they don’t waste time looking for clarity anywhere else. This shows you care about your craft.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
