Following on from the previous article in the series, another "programming in the small" thing that I look out for is comments.
I've been indecisive about publishing this article because it seems so obvious; but I know from seeing code at dozens of different clients over the years that somehow it isn't. I think it's another example of a cargo cult.
A comment on a method "getName" that says "returns the name" doesn't tell you much. I've seen many such comments; usually the result of a project standard whereby all methods have to have a comment. You may think that such a comment is harmless - but it isn't because it takes time to write, time to read and makes the source longer without adding anything.
Even worse than pointless comments are misleading ones. I think it was Weinberg in The Psychology of computer programming who made an observation that when debugging, misleading comments can make it take longer to work out what's happening than if you delete all the comments. Misleading comments can lead you into a truth trap.
Sometimes comments can be useful; for example telling you that some lines of code together mean something, for example "estimated journey time". However, it would be better to extract those lines of code into a method called, for example, "estimatedJourneyTime". Often comments can be an indication that the names of a variable should be improved, or a method extracted.
Kent Beck wrote about comments in Smalltalk best practice patterns - worth reading whether you use Smalltalk or not. I was so pleased to read what he wrote about comments - he expressed clearly what I felt at the time with the code I was working with then.
I think the over-use of comments (and "structured programming") comes from University computer science courses, so maybe I shouldn't be suprised by the prevalence of a belief that comments are good (and many developers, or their bosses, feel they "should" be writing more comments).
From Malte Finsterwalder:
Hi Ivan,
I always remember a quote from the book "Code Complete" : "Don't comment
tricky code - rewrite it!"
Also an interesting observation: Heavily documented code contains more
errors!
Greetings,
Malte
Even the most experienced programmer can learn from pair programming. There's a collection of things that I've learnt over the years since starting pair programming that I don't think I'd have learnt any other way.
Like many programmers, I'm not great at reading the manual unless something goes wrong or I want to know how to do something specific. I'm generally too busy to just browse through a manual and find interesting things. However, when pairing, little tips and tricks come up that I find useful but I would never have deliberately looked for.
I know it's not just me, because, when pairing with other experienced developers (who are less experienced in pair programming), sometimes I'll do something and they'll make a comment like "oh - neat - I didn't know you could do that".
None of the examples here are likely to change your life, but do have some memorability for me personally in terms of things that made me go "oh - neat" that I would not have found otherwise. There are lots of these sorts of things - here's just a sample of 3. Please feel free to add more examples that you've come across by posting a comment.