What’s in a Name? Spelling Matters in Code
Editorial Note: I originally wrote this post for the SubMain blog. You can check out the original here, at their site. While you’re there, check out GhostDoc.
Think back to college (or high school, if applicable). Do you remember that kid that would sit near the front of the class and gleefully point out that the professor had accidentally omitted an apostrophe when writing notes on the white board? Didn’t you just love that kid? Yeah, me neither.
Fate imbues a small percentage of the population with a neurotic need to correct any perceived mistakes made by anyone. XKCD immortalized this phenomenon with one of its most famous cartoons, that declared, “someone is wrong on the internet.” For the rest of the population, however, this tendency seems pedantic and, dare I say, unpleasant. Just let it go, man. It doesn’t matter that much.
I mention all of this to add context to the remainder of the post. I work as a consultant and understand the need for diplomacy, tact, and choosing one’s battles. So, I do not propose something like care with spelling lightly. But I will propose it, nonetheless.
Now I know what you’re thinking. How can caring about spelling in code be anything but pedantic? We’re not talking about something being put together to impress a wide audience, like a newspaper. In fact, we’re not even talking about prose. And code contains all sorts of abbreviations and encodings and whatnot.
Nevertheless, it matters. When English words occur in your code, spelling them right matters. I’ll use the rest of this post to make my case.
The Intellisense Conundrum
If you use Visual Studio, no doubt you make heavy use of Intellisense. To expand, any IDE or text editor with autocomplete functionality qualifies for consideration here. In either case, your tooling gives you a pretty substantial boost by suggesting methods/variables/classes/etc based on what you have typed. It’s like type-ahead for code.
Now think of the effect a misspelling can have here, particularly near the beginning of a word. Imagine implementing a method that would release resources and accidentally typing Colse instead of Close. Now imagine consuming that method. If you’re used to exploring APIs and available methods with auto-complete, you might type, “Clo”, pause, and see no matching methods. You might then conclude, “hey, no call to Close needed!”
In all likelihood, such an error would result in a few minutes of head-scratching and then the right call. But even if that’s the worst of it, that’s still not great. And it will happen each and every time someone uses your code.
Other Manual Typing Errors
The scope of this particular issue goes beyond auto-complete functionality. Perhaps you lack that functionality in your environment, or perhaps you simply don’t use it much. In that case, you’ll be hand typing your code.
Now, imagine hand typing the aforementioned call to a close method. Do you instinctively type “Colse” or do you instinctively type “Close?” So what do you think will happen?
You’ll expect the call to be Close and you’ll type that. Then, you’ll stare in disbelief for a moment at the compiler message. You’ll probably do a clean and rebuild. You’ll stare again for a while and squint. Then, finally, you’ll smack your forehead, realize the problem, and silently berate the person who misspelled the method name.
Again, the impact remains the same. Most likely this creates only friction and annoyance. Every now and then, it may trigger a thoroughly incorrect use of a library or API.
Anchoring Effect
Moving away from the theme of confusion when using a declared member, consider the declaration itself. During the use of a variable/method/class/etc, you must spell it right before the compiler allows you to proceed (assuming a strongly typed language). With the original declaration, however, you have the freedom to spell things wrong to your heart’s content. When you do this, the original copy holds the error.
That first misspelling allows for easy correction. Same goes when you’ve used it only a time or two. But as usage grows and spreads throughout the codebase, the fix becomes more and more of a chore. Before long (and without easy refactoring tools), the chore becomes more than anyone feels like tackling, and the error calcifies in place.
Your unaddressed spelling mistake today makes fixes more difficult tomorrow.
Comprehension Confusion
Let’s switch gears again and consider the case of a maintenance programmer reading for comprehension. After all, programmers do a whole lot more reading of code than they do modification of it. So, a casual read is a likely situation.
Spelling errors cloud comprehension. A simple transposition of characters or a common error, such as referring to a “dependancy” do not present an insurmountable problem. But a truly mangled word can leave readers scratching their heads and wondering what the code actually means, almost as if you’d left some kind of brutal Hungarian notation in there.
Taking the time to get the spelling right ensures that anyone maintaining the code will not have this difficulty. Code is hard enough to understand, as-is, without adding unforced errors to the mix.
The Embarrassment Factor
And, finally, there’s the embarrassment factor. And I don’t mean the embarrassment of your coworkers saying, “wow, that guy doesn’t know how to spell!” I’m talking about the embarrassment factor for the team.
Think of new developers hiring on or transferring into the group. They’re going to take a look at the code and draw conclusions, about your team. Software developers tend to have exacting, detail-oriented minds, and they tend to notice mistakes. Having a bunch of spelling mistakes in common words makes it appear either that the team doesn’t know how to spell or that it has a sloppy approach. Neither of those is great.
But also keep in mind that what happens in the code doesn’t always stay in the code. Bits of the code you write might appear on team dashboards, build reports, unit test run outputs, etc. People from outside of the team may be examining acceptance tests and the like. And, you may have end-user documentation generated automatically using your code (i.e. if you make developer tools or APIs). Do you really want the documentation you hand to your customers to contain embarrassing mistakes?
It’s Easy to Get Right
At this point, I’m finished with the supply of arguments for making the case. I’ve laid these out.
But, by way of closing words, I’d like to comment on what might be the biggest shame of the whole thing. Purging your code of spelling errors doesn’t require you to be an expert speller. It doesn’t require you to copy source code into MS Word or something and run a check. You have tools at your disposal that will do this for you, right in your IDE. All you need to do is turn them on.
I recommend that you do this immediately. It’s easy, unobtrusive, and offers only upside. And not only will you excise spelling mistakes from your code — you’ll also prevent that annoying kid in the front of the class from bothering you about stuff you don’t have time for.
Great points! Another effect of typos has the same impact as any other kind of carelessness in the structure of the code: it lowers the bar on future changes or additions to the code, since you’re much less likely to care about writing careless code when it’s next to other careless code.
I’ve heard this called “broken window theory.” Definitely agree — good point.
There’s another aspect to the auto-complete issue: when a team relies very heavily on that, it can allow misspellings to propagate deeper and deeper into a codebase, making it harder to correct later. For example, if the spelling mistake was “Cloes” instead of “Colse,” other developers may type the first few characters and then auto-complete the error without ever realizing.
That’s a good point. And, as I think about it, I tend to rely on Intellisense by typing the first n characters of a word and then relying on completion. If you messed up beyond that threshold, I would definitely propagate the mistake.
Best Post Ever! As you can tell, there is no way I was that annoying kid at the front of the class… By the way, you ended the article with a dangling preposition.
🙂
My wife, an editor, told me a few years ago that ending sentences with prepositions is considered technically correct. It took a long time for me to convince myself this was really okay, for what it’s worth. So, I’m kinda there with you. With.
Agreed. I think it is more a sign of when one studied English grammar as to whether one “struggles” or not with dangling prepositions. While they may now be considered technically acceptable, I think avoiding them can often improve the readability of sentences, as it tends to put the prepositions closer to (if not adjacent) the objects to which they refer – as in this example. This is especially true with more complex sentence structures, which seem less popular in the Internet Age. Had I constructed this reply as a single sentence, and ended it with the word “to”, you’d… Read more »
As the famous Churchill quote goes, not ending a sentence with a preposition is “the sort of nonsense up with which I will not put”.
😀
I’m still fighting with the newly-acceptable “myriad of.”
(I just retyped the period-quote sequence three times.)
I didn’t realize that was considered ‘correct’ phrasing. Feels redundant to me, but I’m happy to change with the times. The one I’ve always kind of struggled with is “the reason why x…” It always feels like “reason” implies “why” without specifically calling it out.
Yup. I cringe when I hear “… for a myriad of reasons” and think, “damn you. it’s for myriad reasons!” But, so many people mess it up, the former is now considered acceptable as well. And a neat English word dies a little.
Reluctantly playing the Devil’s Advocate, I’ll proffer a benefit to misspelled words. If you know that the method you are looking for starts with “Cloes” (because its appearance was so notable, of course), a global search and/or replace in the codebase will be more successful without all those pesky cases of “Close” popping up!
An amusing point, though in reality I would abhor any fellow developer doing a manual replace across the codebase o_O. That’s what your IDE is for! (to also touch on the other discussion above ;-p )
A similar question about how words are spelt surrounds the UK/US spelling issues of colour and other such cases. Even worse is the high-falutin words such as manouevre/manoeuvre. I’m aware of a multi-nation colaboration that one was said to have half a dozen ways of spelling it! (It was a defence programme). There is a big list at https://en.wikipedia.org/wiki/Wikipedia:List_of_spelling_variants. Choose one style and try and stick to it.
Definite wisdom in that last sentence there. I think consistency across the expectations of people interacting with it is the biggest thing.
Those of us who glare in disgust at https://en.wikipedia.org/wiki/HTTP_referer salute you! I will never understand how coders, who must spell all keywords and library function names correctly all the time if they want their programs to work, can be so lackadaisical about spelling in general. But I do have a terrible curse that makes my brain come to a screeching halt when I encounter a misspelled word, so your mileage may vary. Dyslexic people surely find spelling to be a vexing difficulty.
Personally, it doesn’t annoy me terribly. It seems a little sloppy and if it causes a “principle of least surprise” violation like I mentioned in the post, then I get annoyed in earnest.
If the spelling doesn’t have any effect on code quality I don’t bother it and it doesn’t bother me. Just recently I have seen how core code in Java and Java EE has some howling mistakes but they are just in messages. Spelling mistakes in actual code I do care about. I just refactor it out and get on with it. I work in Germany, most code bases are coded using English. Mistakes happen. In fact the standard of English is, in most cases, better in German code than in some prominent English/American based code bases I have seen.
What you’re saying doesn’t surprise me about the quality of the language. Anecdotally, at least, I’ve seen a number of instances where not taking language for granted made you more inclined to get it right.
There was a method in the Java API (in the swing package if my memory is good) that was misspelled. They add to keep it alongside the method with the corrected name because of the backward compatibility. It’s still probably here, and will always be here for all eternity …
There’s nothing like having a mistake you’ve made calcify and remain for all of eternity, for everyone to see.
“Spelling Matters in Code”, and grammar matters in writing about it. You wrote, for example, “When English words occur in your code, spelling them right matters”. “Right” is an adjective, and as you were modifying a verb you needed an adverb. “…spelling them correctly matters” works.
Pedantic? Moi? (to paraphrase Miss Piggy)
For what it’s worth, I was making the case that one should pay attention and do one’s best, as opposed to claiming my own infallibility and using that as a pretext to criticize others. I won’t keep anyone in suspense — since I write my posts off the cuff, you will find grammar and spelling errors in just about every one of them, if you look hard enough. That said.. Pedantic? Maybe, dunno. Accurate? It doesn’t look like it. http://dictionary.cambridge.org/us/grammar/british-grammar/right-or-rightly “Right is an adverb of manner. It means ‘correctly’ or ‘well’.” So, by way of riposte, I’ll say that grammar… Read more »
A sound argument to underline an issue that is rarely considered. Well said, and thanks for taking the trouble to say it. 🙂
Thanks for the feedback — glad you liked!