Comments for Comments Sake

I was coaching in St. Louis, I think early 2010s; it's where I met Dave Rooney.

I was discussing the role of comments with the lead developer. It was one of those shops that not only puts JavaDoc style comments on private methods, but meticulously keeps them perfectly up to date.

I told him comments should explain why or how since the code explains what plus comments lie. He swore up and down their comments never got out of date and were meticulously maintained. My first thought was what a monumental waste of effort, but my second and more accurate thought was yeah, right.

He watched me randomly select a file, quickly scan it, and immediately find a method that had been copied and pasted to remove a parameter. How did I know? The comment was exactly the same as the comment on the previous method; clearly listing the name, type, and role of a parameter that did not exist.

He claimed that instance was an anomaly. Rather than explain to him the statistical improbability of finding the only case of a comment that lies in a meticulously maintained code base, I scrolled down and found another example.

I didn't bother looking for a third as I could see he was unmoved and continued to demand comments designed for documenting a public API be added to private methods.

I let it go and moved on because I had already given it more time than it deserves in the grand scheme of coaching agile technical practices during an agile conversion.