How do you feel about spelling errors in code? I wrote about them for SubMain on their blog.
You’re checking out some code. It’s been a long time since you looked at this project. Or maybe it’s the first time. You point your editor at an interesting file name and double-click to open it. Your coffee is warm, your mind is clear, and you’re ready to go.
And there it is, sticking out like white socks in sandals. A spelling error.
How do you handle it? Do you fix it? Do you ignore it? Discuss it with the author? Bring it up during lunch when he’s not around?
What Really Matters?
Speaking personally, this isn’t an easy question to answer. I write code for a living, and I understand what it means to be in a hurry and not have the bandwidth to worry about spelling and human grammar.
But I write words for a living, too. Spelling and grammar errors scream out to me, like a crooked painting in the Louvre.
On the other hand, if there were a Nobel for typos, I would be a contender. I usually fix them before I check in code or submit something to an editor. But not always.
How you react to spelling errors in code comes down to how you answer another, more fundamental question. What’s really important when it comes to evaluating source? Whether or not it works? Whether or not it can be understood? How correct it is?
That last question is the tip of the proverbial iceberg. What does “correct” mean? Most answers would include references to functionality, tests, maintainability, and best practices. Where does spelling fall on the correctness spectrum?
Does spelling matter?
Code Is for Coworkers
A few years ago, Derick Bailey wrote that code is for coworkers. He was referring to how we construct source code and, by comparing obfuscated code to the original source, illustrated that we write code for people. The computer doesn’t care how readable code is, but for humans, readability is critical.
The ability to look at your code and ask yourself “will anyone else be able to understand this?” is what separates a pro from a beginner—or worse, a hack. If another developer can’t understand your code, it’s not maintainable. It’s worthless.
But can misspellings render code unmaintainable?
The Case Against Spelling Errors
One problem with spelling errors is that you have to be aware of them to understand the code. If a “widget” is a “wdiget,” you have to know to search for the misspelling to find it. So, if the author has misspelled an important object or concept, the error is a frequent obstacle to understanding and fixing the code.
But misspellings are rarely that easy to navigate around. Most spelling errors are inconsistent. Widget is usually spelled correctly in 90% or more of the places where it appears. “Wdiget” only appears in one or two locations. This renders those uses invisible from searches. Even the most sophisticated refactoring tools can’t reconcile a spelling error with the correct spelling.
If spelling errors are not fixed immediately, situations like the one above will start to proliferate, rendering parts of your code unmaintainable.
The Case for Letting Spelling Errors Go
Of course, if a spelling error is making parts of your code opaque, you have more significant problems. Code that is so fragile that a handful of misspelled words impairs its maintenance must suffer from other design issues.
Why are you relying on grep or other search mechanisms to navigate through your codebase? Even if you inherited the source from another team or developer, text search is only one of many tools. Object and file names, external documentation, debuggers, and profilers are better ways to figure out how things work. A brute force file search is a last resort.
Spelling errors are a deficiency, and we should treat them as such. We should fix them and make an effort to avoid them, but there’s no reason to hold them out as a special class of problem.
But Should You Hold Spelling Errors Against Developers?
Ah yes, the original question. I thought you might let me off the hook on that one.
No, you shouldn’t hold spelling errors against developers.
What if the offender doesn’t speak native English? English spelling is atrociously inconsistent and is often an exercise in memorization. A developer’s number one focus should be on writing good code. Mistakes in a second language should be forgiven. If you’re willing to help a coworker learn how to write code, you should be willing to help with English too.
Or they were in a hurry. A spelling error is, at worst, a minor bug. Have you ever written buggy code while you were in a hurry? Me too. How about when you weren’t in a hurry? Yeah, me too again.
If you’re asking this question, it’s safe to assume that the offender is someone you work with. If you can “hold it against” them, it implies some real-life consequences. Maybe they work for you, and you can make things difficult for them. Maybe they’re a co-worker, and you’ll stop trusting them.
So What Should I Do About Spelling Errors?
So here’s an idea: fix them.
What would you do if you found an off-by-one error? An uncaught exception? A memory leak?
Regardless of how you feel about how serious a spelling error is, your first reaction should be to fix it. You’re in the code for a reason, and unless the goal is some recreational reading, correct the error. The only reason to delay fixing the spelling would be that it risks a regression, such as renaming an object or method that’s dynamically linked.
If you can’t fix it on the spot, you’ve got two options. Open a bug for it, or if that might cause embarrassment for someone, go to them and work out how to address the problem.
The key concept here is this: it’s a mistake. Nothing more, nothing less. We all make them. The best way to deal with a small error is to fix it and move on. The best way to deal with a larger one is to make arrangements to have it fixed.
If you’re working in a culture where pointing out mistakes is a problem, it’s time to move on. Enough said.
Can’t We Avoid Spelling Errors in the First Place?
Most code editors and IDEs have some degree of spell check support. It’s not foolproof, and most source code is going to be full of false alarms. But you can turn it on and work on training it to learn your dialect.
And of course, there’s GhostDoc. GhostDoc can help you build excellent documentation for your code, and it catches spelling errors, too!