Member-only story
Writing a clean code is not enough in order to build a clean code base, also a clean documentation is required to achieve a clean code base.
Good documentation is essential for the readability of the code and also it is a must-have in order to operate and maintain the code in an efficient way. As remote working is a favorite way of working nowadays and collaboration with in high number of colleagues is really required today, documenting the code is also required.
So, what is a good code base documentation? From my point of view and from my experience, a good documentation should have;
- A crystal clear expression and an easy language while documenting
- Each class, method, field should be described not with as much as detail it should have, they must be detailed.
- Reference & linking between components should be used in order to increase the readability.
- Documentation should be kept up-to-date all the time in order to preserve consistency.
- Documentation must be done easily within the code.
- Software document must be generated easily and it should be easy to understand for everyone and for every level of developer.
I will cover Javadoc in this article for software documentation. All LTS (long time support) JDK versions support Javadoc. Javadoc is generated from Javadoc comments which are similar to regular comment blocks in Java.
I have already added Javadoc comments to all class, methods, fields in my open-source Spring Boot example project. You can reach this project from spring-boot-project-example repo in my Github profile.
As seen in the example code snippet, Javadoc comment is similar to regular comment blocks in Java, except an extra asterisk while starting the Javadoc comment.
Below screenshot is from the generated Javadoc of the method specified in the above code snippet.
