Coding manners matter
I was thinking the other day about coding standards, and what’s considered good coding practice. Let’s consider a handful of examples:
- neatly laid-out code (indentation, line length, etc)
- informative variable names
- inline documentation/comments
When we work in coding teams we tend to hammer this into people. Most software projects have a “house style” of some sort, to which all contributors are expected to adhere. Newcomers sometimes take some convincing, but most get there in the end.
We usually say that we have coding standards and style guides because it improves code quality, or makes the software easier to maintain. That’s certainly true. But it occurred to me a while ago that coding standards are also a matter of etiquette.
By conforming to a coding standard, we smooth our interactions with the rest of the team.
That one guy who always uses tab characters, or names his variables LikeThis instead of like_this, isn’t just making the code worse; he’s driving everyone else nuts with his rudeness.
7 Comments so far
Leave a reply
I hadn’t thought of it that way, but you’re right. Worse Than Failure had an example of this recently where a coder was obviously trying to get around in-house coding standards by being clever. But it’s really not clever, it’s just rude (and so are the people defending the coder, although they don’t realize it).
Anitra: augh!
“Comments!”
Comments are for academics!
No, seriously. I know I’m probably bordering on AS here but I hate ‘em. I like some at the top of a function telling you what it’s meant to do, what the parameters are, etc., but I genuinely find in-line comments make it harder to follow the flow of the code.
With the advent of structural (I’ve been doing this since ‘82) and object based coding methods, most code is almost self documenting. If anything is so long and complex is needs documenting in-line, it is probably a candidate for breaking up into functions (with header comments), leaving you with a self-documenting list of function calls.
I do, however, add them (at the end of development) for politeness and so I don’t get lynched at appraisal time. But I genuinely have never worked out what they are for though – personally I find the cold straight-forward logic of the coding language itself much easier to follow than a more abstract verbose explanation in the code – plus you see what the code is actually doing now, not what the original programmer intended it to do. When I was first starting out, the code I was working on was 20 years old and adapted so many times the original comments were often completely misleading.
Good blog btw – made me laugh, and good advice. Sorry if the comment is a bit long – I’ve pruned it a lot!
I definitely agree with Matt Langley. Most code I write is so short / self-documenting, writing real POD for it would usually double the amount of text.
The only time I will write POD is when I’m describing an API. That way, I have a set standard I have to code to.
Matt, imMute: if your code really is “self documenting” then it serves the purpose of communicating with any future maintainer, so as far as I’m concerned that meets the politeness criterion. On the other hand, I’ve seen lots of code that people *claim* is self-documenting, which really isn’t. I have a related rant on how people comment the wrong things (i.e. what the code is doing) instead of the things that are hard to discern from the code itself (why you’re doing it).
Heh, it so happens that I just wrote an entry about comments in code…
Phew! I was worried…
I guess the test is whether you can work out what you were thinking when you come back to it a year later.
(I definately agree that any comments should add some insight rather than describe the code.)