For beginners, code documentation is known as the green comments in the code. Any experienced programmer will tell you that code documentation is one of the most important aspects of programming. The major reason why it is important is because it is how developers communicate with other developers. But let’s look deeper into why code documentation is important.
Working on large projects
As your skills in programming develop, the projects you work on will get larger and without code documentation, you will start to lose track on what you are trying to implement and achieve. With programming, especially if you’re a beginner, you can easily get lost with what you are doing and code documentation helps keep you on track.
If you decide to work on software projects with other developers, you will no doubt have to document your code. As stated in the beginning of this article, code documentation is how you communicate with other developers and if you don’t have any documentation, you are going to confuse the other developers and make their job harder because they may not understand what you are trying to implement.
Clarity and understanding
Let’s say for example you write a complex program with over 500 lines of code without any documentation, and you forget about it and open it up six months later. You are barely going to understand or remember what you were trying to achieve. Documenting the code would of have saved you hours of frustration of running around in circles trying to piece everything together again.
When you are programming something complex, you will definitively need to break down what is happening with the help of code documentation in order to remind yourself and other developers what your objective is.
How to properly document code
We now understand the importance of code documentation, but now let us look at how to properly document code.Here an example of how not to document code.
Why is this a bad example? Even if you a complete beginner and not a programmer, everyone would be able to understand this line of code. We are simply adding three to the variable “a”. This is a bad example because it is documenting the complete obvious. You don’t have to document every single line of code, because there will be lines that are obvious and absolutely simple to understand.
Now let’s look at a proper example
This code sample was used in my projectile motion simulation assignment in my C++ class at university. It looks complex doesn’t it? Heck, I couldn’t even understand it the first time myself. This is an excellent example of how I am not documenting the complete obvious. The code documentation in this example is providing clarity and understanding of how the x and y coordinates are calculated to myself and other students reading the code. Without it, myself and others would not have a clue what the objective is.
