How to write good software technical documentation
--
This article aims to help developers to write better documentation. As a developer, I hate writing documentation. But I hate even more reading undocumented code. I describe here what I expect from a good documentation and why it is necessary.
First of all, you need to understand you are not writing documentation for you, nor for your current team. You are writing documentation for the future developers that were not there when you first wrote this code. Worst of it, they might think it is bad code for many reasons and won’t understand why you wrote this way.
Code documentation
I often hear that a good code does not need documentation. I totally agree with this statement. I am not here to explain how to write good code but good documentation. If you want to know how to write good code, you can start by reading this : https://medium.com/@isaaclyman/steps-to-better-code-e6c3cce0c7f9.
Naming should represent 99% of the documentation of your code. No need to add unnecessary comments to explain what you’re trying to do. It’s like as a French translator, you write some English comments in your translation for the next person that will update your work. We can easily guess that the next translator speaks both French and English, so he doesn’t need the text in both languages. It is the same with a developer: he can understand both code and natural language. So you don’t need to write English translation of your software code.
Here is an example of unnecessary comments :
# Example of unnecessary comments// This function will process orders items attributes
function processOrdersItemsAttributes(orders: Array) {
// I iterate the orders
foreach (orders as order) {
// I iterate the orders items
foreach (order->getOrderItems() as items) {
// I iterate the items attributes
foreach (items->getItemAttributes() as attribute) {
// I process the attribute
process(attribute)
}
}
}
}
Functions & Methods header comments
Today, IDEs can automatically generate function and method headers comments (see example below). These comments can be transformed…
