Code Documentation Is Underrated

So when we write code, we believe everyone should understand what it is we are trying to tell the computer to do. We use some naming conventions that seems really nice to us to explain what it is we really have in mind and believe the next programmer that would look at our code would have the same exact thoughts and ideas in mind.

Oh no, guess what. Even if you are to come back to the same code after a few weeks, you look lost at a code you wrote yourself just a few weeks ago. It is fundamentally important to always explain what exact logic it is you want to explain and how you want it explained.

The above code rather looks easy to follow through but I would argue it requires a lot of comments. Why do we need to know who created it, why do we check if it is modified. What is the essence of the getNextId? How does the getNextId work. These are many more questions you would ask yourself if anything goes wrong with the code in the next 3 years.

Always explain the exact logic of what it is you want to achieve and how each line of your code helps you achieve it. It might take more time to complete writing your code but it would as well save you and the next programmer that would work on the project less time to understand what exactly it is you want to achieve.

Keep it simple always. However, explain exactly what it is in your mind you want the computer to execute. It would always be needed in the long run.

Thanks for Reading and Sharing

Leave a Reply

Your email address will not be published. Required fields are marked *