Besides the ability of abstract thinking and a more or less deep love for sciences such as mathematics and physics, another very important feature of a programmer is certainly the drive to explore the New and the desire to create.

But in contrast to other professions whose work results in crafted tools and objects, the programmer also needs to think about others. Nowadays designing and programming software is rarely a one-man task, but involves other people as well (sometimes even people from other professions). To make it more easy (or sometimes even possible) to read and understand the written code the programmer has to add a layer of abstraction and explanation to his creation. The term for this is “commenting“.

Comments are not meant to retell the code’s intention in the parts that are anyway obvious, but to underline the meaning a certain junk of code bears. If a certain algorithm has been implemented the programmer is advised to explain the choices he made during the implementation. Especially in terms of algorithms fellow programmers most likely would have a very hard time to understand the implementation and it will be hard for them if they have to make changes or additions to the codebase. It is always wise to comment certain choices made during the development process and why a certain option was chosen in favor of other possibilities.

A very nice side-effect on commenting code fragments as well as purpose and usage of methods and functions it the ability to automatically generate parts of the projects documentation from it. A quite popular tool to do so is Doxygen. This makes compiling comprehensive documentations much easier.

And even if you’re working on a piece of software just for yourself: You’ll find yourself delighted if you check some code you’ve written a couple months ago and can immediately understand what you was thinking back in the time when that code mirroring in your eyes was written.