Understanding documentation

For many programmers in general, documentation is viewed as more of a petty pain than anything else. However, proper code documentation is vital to the longevity of a codebase. With that being said, it is often not clear what should be documented or, for that matter, how to properly write documentation.

The past code examples were easy enough to understand when the proper context was provided. However, if the context was taken away, chances are you would have a difficult time figuring out what the code did. In practice, this is very bad. Other developers that inherit your work should be able to open the project and understand the code with minimal effort.

Documentation also helps you personally. Let’s assume that in 6 months when your customer wants an upgrade, you’re going to be the one who is going to implement the upgrade. Chances are you’re not going to remember how the code works. There is no silver bullet that’ll make...