Commenting your code – why not what.
Today I had to modify a small part of our flagship product; this particular part was written about 2 years ago by developer who is no longer working with us. Back then we did not have too much time on our hands to actually maintain some kind of coding standard. The variables are named poorly, there was no history of the class modifications, but there was one part of the project that looked promising – he did leave comments.
Unfortunately the comments that were there did not help me at all. Here is the problem – the developer who wrote the classes I needed to modify went out of his way to block a certain type of input by user. Input strings were checked couple of times as well as an event was called to verify input on every key press. And guess what – I have to have the form and the code behind to accept this type of input against which this developer fought so hard. While it did not take me long to disable these road blocks, I still can’t understand why were these things blocked.
The comments were there, and they were describing what was the code doing and not why. Realistically speaking, any developer can read code and get some idea what is happening, you don’t need to comment it, I was searching for an explanation why and I did not find it. There was no unit testing provided, so I have no idea what my changes do to the stuff that was already written and I have no reason to be certain what will happen to the code until we test it, and trust me, this will be the most tested area for this new release. Did I needed to see explanation of how a foreach loop is executed – no; would I love to see explanation why this input was blocked – YES.
