“Commenting is a royal pain in the posterior” - “Comments are for weenies” - “I can understand my code quite well, thank you very much” - “Good code speaks for itself” - “No time for that, got to get that code out of the door”. Admit it, you have said some thing along these lines at least once during your coding career. Maybe you even now still are in this kind of frame of mind. Negative attitudes towards commenting may have several reasons:
Programmer’s hubris
Lazyness
No time left for documentation due to deadline constraints

None of these is a good reason for not commenting source code properly. We will look at these arguments, discuss them and take a look at good commenting practice and its benefits. As SharpDevelop is intended to be an IDE for all languages supported by the .NET platform – and others, if support is available – this text will not discuss language specific commenting issues. Knowledge of all languages referred to is not necessary for the understanding of this paper.

Programmer’s Hubris
A good programmer is always a programmer with something of a well developed ego. Nothing is impossible, everything is easy to understand. So much for theory. In practice, reality checks are in order from time to time. Do you understand all your code after not looking at it for, say, a year? Is legacy code left to you to maintain always obvious at first look, or even after a few weeks of scrutiny? Truth is, most of the time it will take a lot of time and effort to understand undocumented code, even if the code has not been obfuscated intentionally.

Download pdf The fine Art of Commenting