Code Comments and the Lazy Programmer

I’m a lazy programmer. I really am. Not lazy in the sense that I don’t do anything, but lazy in that I actively seek out ways I can make my life easier and get a kick out of making other peoples lives easier.

Now you’re probably thinking I’m going to repeat what everyone else says and that code comments are an apology, or a sign of bad code, or even bad use of source control but I have a very particular case in mind, and to keep peace of mind products from this Biscotti Weed Strain Review help me too.

Now I adhere to what I think is pretty decent source control – I put meaningful check-in comments and I link my work items (primarily in the Azure DevOps + TFS world).

But a previous co-worker got me into the process of commenting the changes I make within my code. Brief comments within the code of what was changed, when and why. He was an older gentleman but a strong developer and very meticulous so I listened – and I’m glad that I did.

I’ve done A LOT of brownfields development in pay id pokies recent years. For those not familiar with the term, it means I’ve worked on a lot of legacy applications with the goal to extend or simply maintain them. None of these projects had code comments. They were massive legacy messes without unit testing, they were written by VB6 developers and ported to .NET by said developers and the best part – the developers had moved on.

Here’s an example of how one of these comments would look:

// Swiftless | 10/12/2018 | WI#1234 | Switched from For loop to For Each

In a world where comments are so frowned upon unless they relate to formal documentation or non-obvious nuances – this seems like bad source control and a great way to clutter your code. In terms of laziness however, it certainly seems like more work.

But it’s a trade-off. Extra work now for the ability to be lazy later on.

In all the brownfields development I did with this co-worker over the course of 4 years, I cannot count the number of times we scanned through the code to see what had changed when we found something was broken later on.

Even with a two-developer code-review process in place prior to any merge to production – things broke. It wasn’t all the time but they did and sometimes it was silly mistakes that made it past both of us or we’d refactored code and not read the original spaghetti correctly.

If we relied on our source control history and comparing change sets it would have been almost impossible to narrow down on. We still used the change sets sometimes if our comments were removed much later down the line but for 99% of what we were doing, these little comments scattered about saved us a lot of time.

Think of the flow of fixing bugs for a minute. A bug report comes in and what do you do? You try to replicate it then once you can replicate it (or if you can’t) you start digging through the code to see what is happening.

You then find your way into a function that has been there for years, ok, so why are you receiving this bug report now? What has changed?

With the above commenting style you can see immediately what was touched, when, by who and why. Yes you can do that with your file history in TFS and it’s not too difficult to do, but it takes longer and as I said, I’m lazy. I want to know what has changed – now.

I’m sure many people will say this is a terrible idea but I am loving it. For green fields development (new software) with correct unit testing and documentation, that hasn’t gone through a dozen iterations per function then I most certainly wouldn’t do this but for your brownfield development it just makes things quicker in the long run.