Commenting on Code

Posted on Thursday 20 September 2007

I thought I should give you all a heads up that I will be playing around with my template a bit today. While reading and studying is good, nothing beats actually doing it to understand how things are working.

None of the content will be lost, you just might see some extra items appearing on the page from time to time. Please ignore it if you can ๐Ÿ˜‰

I am starting to get a real appreciation as to how things work with CSS/stylesheets and PHP isn’t half as intimidating as it used to be thanks to the two great books that I mentioned earlier.

<– Stepping onto the Soapbox–>

When I was managing a development team, a long long time ago, I used to insist that the team leader ensure that comments were numerous and clearly written, so that the next programmer who came along could understand/modify/continue what was already done without having to jump through too many hoops.

I got a lot of push back from that gang. While the team leader understood the need, the programmers only wanted to do what they loved doing best – programming. I can’t say as I blame them, once you get into “the flow” time can fly, and you feel like you are making great progress. So, it can be very hard to pull ones self out and then spend time (I recall one or two of them said “waste time“) writing comments to explain what the program was or should be doing.

My efforts were only partially successful… My programming team was eventually moved to another unit and they happily went about their job of writing yet other programs. However, one of the key pieces of code that had been written needed to be updated from time to time. No one would touch it, because they didn’t know how it worked and didn’t want to spend massive amounts of time trying to figure it out. That program followed the original programmer around for years!

When I retired, the program and programmer in question were still tied to the hip. That wasn’t the only example in my building either, there were many others but it was one that I tried really hard to stop from happening, and didn’t quite succeed!

So, for any programmer out there, document your code and do it well! If you think disrupting your chain of thought to write comments is bad, try being pulled out of your project entirely to wrap your head around a problem with some code that you may have written years ago! It has happened and ,unfortunately will probably happen again – so don’t get caught! Document it!

<–Stepping off the Soapbox–>

Suffice to say the code I am working with has “some” comments sprinkled about it. It just doesn’t have nearly enough for me to follow all the various trains of thought in them. So each step is taking me a while…

Thanks for your patience, and if you have any to spare right now…. could I borrow some! ๐Ÿ™

End Article

Please Add Your Comment. PLEASE NOTE: Your comments WILL be held until authorized by the webmaster.