Documentation is the instruction manual that explains how code is structured and, consequently, how it works. This is often accomplished by outlining the arguments that the function or method anticipates, the body of the function, and the results of the function. For a variety of reasons, code documentation is important. Well-documented code is simpler to maintain and update, and future developers will have a better understanding of the codebase as they will know where to make modifications when adjustments are required. Documentation may also assist in learning from the errors we made today so that we don’t make the same ones again when working on future projects. 

 

Nobody Has Time For Documentation

Rarely do we have time to stop everything we’re doing and concentrate on documenting our code when working on a project that has a deadline. Whatever you are doing, there’s a good chance you or a colleague will need to review the source code at some point. It will be difficult to recall what you wrote and why as clearly as it was on that day. And even if you get to remember what you wrote, there might be some edge instances or particular uses that aren’t immediately obvious. Documentation becomes the obvious option.

Spending a little more time now to properly describe the work you did will pay off in the long run. The next time someone wants to understand what happens inside your code, you will only have to point them to the detailed documentation. Both you and they will save time since you won’t need to explain things to them, and they will save time because they won’t need to rely on you.

 

Some Principles To Consider

1. The documentation should not be ambiguous but precise and to the point.
2. In terms of context, it should be from the point of view of the person reading the code.
3. Assume the person reading your code knows nothing.
4. Should describe how the codebase has been organized in terms of structure and how the various components interact. A description of the design pattern used is equally important. 
5. Document bugs and how they got solved.
6. Document changes made to the code and why they were made.
7. Making use of glossaries to aid the reader in understanding terms that directly relate to a subject
8. The documentation needs to be up to date, updates/changes made to the codebase would require a similar update in the documentation for relevance. 
9. Documentation should be a collaborative affair more so if the codebase had more than one author.
10. Getting rid of what is not being used dead is essential especially when the same could become a source of misinformation. 

 

 

Nested Code

Conditionals are primarily responsible for nested code. We can’t really get rid of conditionals because they are the foundation of all programming logic. We must be aware of how they affect the reading of the source code.

An important aspect when reading nested code is the number of levels the nested code has. The more levels, the more complicated it gets when reading the source code. When reading source code, we ideally intend to create a mental model of the program’s behavior. Readable code requires less effort to create and maintain the mental model than code that is hard to read. 

An example of nested code, as you can see, it takes some time for one to get around and there’s a possibility of misinterpreting what the code intends to achieve.

 

The above code snippet is an example of nested code, its understanding is subjective to the author and will be difficult for anyone else to understand and create a mental model. Possible solutions for this could be:

1. Document each line of the code to give a detailed explanation of what was to be achieved. 
2. Refactor the different nested blocks into separate functions.
3. Use of guard clauses

 

Example

Below are screenshots and the actual Java files demonstrating how the documentation has been done on the selected classes. It is a part of a bigger project that can be found here

Link to the documentation example: https://bit.ly/3UuF4kd

 

Symatech Labs is a Software Development company based in Nairobi, Kenya that specializes in Software Development, Mobile App Development, Web Application Development, Integrations, USSD and Consultancy.