I was working at Unisys two decades ago when I first got into the discussion of what traits, characteristics, or skills to look for in programmer candidates we interviewed. One of the elder team members shocked me when he said he tried to hire musicians regardless of prior programming experience. His feeling was that anyone could learn a language, but people who wrote music understood composition and flow, far harder skills to teach. At the time I thought I understood what he meant, that good code has very little to do with individual statements or programing language used. And the people he hired did make mistakes with the language, but their applications were well thought out. Still, it took 10 years before I fully grasped why this approach worked.
I got to thinking about this today when Rich forwarded me the link to Esther Schindler’s post “If the comments are ugly, the code is ugly”.
Perhaps my opinion is colored by my own role as a writer and editor, but I firmly believe that if you can’t take the time to learn the syntax rules of English (including “its” versus “it’s” and “your” versus “you’re”), I don’t believe you can be any more conscientious at writing code that follows the rules. If you are sloppy in your comments, I expect sloppiness in the code.
Thoughtful and well written, but horseshit none the less! Worse, this is a red herring. The quality of code lies in its suitability to perform the task it was designed to do. The goal should not be to please a spell checker.
Like it or not, there are very good coders who are terrible at putting comments into the code, and what comments they provide are gibberish. They think like coders. They don’t think like English majors. And yes, I am someone who writes like English was my second language, and code like Java was my first. I am just more comfortable with the rules and uses. We call Java and C++ ‘languages’, which seems to invite comparison or cause some to equate these two things. But make no mistake: trying to extrapolate some common metric of quality is simply nuts. It is both a terrible premise, and the wrong perspective for judging a software developer’s skills. Any relevance of human language skill to code quality is purely accidental.
I have gotten to the point in my career where a lack of comments in code can mean the code is of higher quality, not lower. Why? Likely the document first, code later process was followed. When I started working with seasoned architects for the first time, we documented everything long before any code was written. And we had an entire hierarchy of documents, with the first layer covering the goals of the project, the second layer covering the major architectural components and data flow, the third layer covering design issues and choices, and finally documentation at the object level. These documents were checked into the source code control system along with the code objects for reference during development. There were fewer comments in the code, but a lot more information was readily available.
Good programs may have spelling errors in the comments. They may not have comments at all. They may have one or two logic flaws. Mostly irrelevant. I call the above post a red herring because it tries to judge software quality using spelling as a metric, as opposed to more relevant attributes such as:
- The number of bugs in any given module (on a per-developer basis if I can tell).
- The complexity or effort required to fix these bugs.
- How closely the code matches the design specifications.
- Uptime during stress testing.
- How difficult it is to alter or add functionality not provided for in the original design.
- The inclusion of debugging flags and tools.
- The inclusion of test cases with source code.
The number of bugs is far more likely to be an indicator of sloppiness, mis-reading the design specification, bad assumptions, or bogus use cases. The complexity of the fix usually tells me, especially with new code, if the error was a simple mistake or a major screw-up. Logic errors need to be viewed in the same way. Finally, test cases and debugging built into the code are a significant indicator that the coder was thinking about the important data points in the code. Witnessing code behavior has been far more helpful for debugging code than inline comments. Finding ‘breadcrumbs’ and debugging flags is a better indication of a skilled coder than concise grammatically correct comments.
I know some very good architects whose code and comments are sloppy. There are a number of reasons for this, primarily that coding is no longer their primary job. Most follow coding practices because heck, they wrote them. And if they are responsible for peer review this is a form of self preservation and education for their reviewees. But their most important skill is an understanding of business goals, architecture, and 4GL design. These are the people I want laying out my object models. These are the people I want stubbing out objects and prototyping workflow. These are the people I want choosing tools and platforms. Attention to detail is a prized attribute, but some details are more important than others. The better code I have seen comes from those who have the big picture in mind, not those who fuss over coding standards. Comments save time if professional code review (outsourced or peer) is being used, but a design specification is more important than inline comments.
There is another angle to consider here, and that is coding in the open source community is a bit different than working for “The Man”. This is because the eyes of your peers are on you. Not just one or two co-workers, but an entire community. Peer pressure is a great way to get better quality code. Misspellings will earn you a few private email messages pointing out your error, but sloppy programming habits invite public ridicule and scorn. Big motivator.
Still, I maintain in-code comments are of limited value and an old model for development that went out of fashion with Pascal in the enterprise. We have source code control systems that allow us to keep documentation with code segments. Better still, design documents that describe what should be, whereas the code comments describes what ‘is’ and explain the small idiosyncrasies in the implementation because of language, platform, or compatibility limitations.
Spelling as a quality indicator… God, if it were only that easy!
Reader interactions
8 Replies to “Ur C0de Sux”
Haha, you’re right to mention those are quotes, not apostrophes. That’s what I get for commenting during work. 🙂 00p5!
But, I’m just saying that grammar and correct writing don’t really have a ton to do with how well someone codes. If someone writes comments with proper punctuation and another dev writes comments with coder punctuation, that really doesn’t have a bearing on their code skill.
LonerVamp,
The quoting style above is deliberate, and not an error. Note that those are quotes, not apostrophes.
http://catb.org/jargon/html/writing-style.html
>Bad:
I think the relationship between code grammar correctness/spelling is too loosely related to code quality to be much of an indicator. It would be a stronger case if you’re talking about how concise or appropriate or formatted code may be, or how present it is at all! But grammar and spelling, I agree, is a silly red herring. This might be like saying because you aren’t meticulous with your appearance and hair style that you can’t be meticulous with your code. There may be a loose relationship, but it can’t be that meaningful.
Besides, there are at least 3 examples of common coder-to-writer grammatical errors above, where an apostrophe is closed off before sentence punctuation. Bad: “Hello”. Good: “Hello.” I’d never seen this until around 2000 when more and more folks started learning the basics of coding which would dictate you close nearest things first; much more akin to math than language!
But that’s being horribly nitpicky and really doesn’t tell me anything about how well someone should code or how much attention to detail they have, when you really get down to it.
My opinion should be taken lightly, as I only work near real developers and do not begin to call myself one. I just poke at code with a stick.
I’ll echo the others and disagree with you on this one, and I think your response to the first comment proves the point when you say that:
>>
Spelling and grammar, to a coder, are things caught by pre-processing and compilation. It will fix your code but not your comments.
<< If I was managing a team of developers and one of them told me the above, s/he'd be off the team in a heartbeat. Talk about sloppy... Also, I agree with the commenter who pointed out that documentation, even if in version control, is likely to be neglected sooner than the code. I'd bet code is quite evolved after 5 years of life, but the project team that built the code is long gone and updating external documentation is an afterthought at best.
Having worked on more different commercial software products than I care to think about, I agree that lousy commenting is not necessarily indicative. However, I’d submit that the inverse *does* prove something: well commented code is good code. I’ve inherited far too many poorly documented, poorly coded products — and a smaller number of well documented, well coded products — not to believe this.
I’m glad, however, that you didn’t fall for the all-too-common “the code is the documentation” hogwash. I sat in a meeting where a VP of Engineering told us not to comment our code “because the comments might not match what the code does”. As opposed to, say, the code not matching what it’s *intended* to do, with no way of determining that.
I must add that your theory that poorly commented code reflects documentation elsewhere is unproven in my experience. Occasionally that’s been true, but in general, poorly commented code I’ve seen reflects a lack of documentation in general. I’ve been told “Just look at the header files”, only to find that the comments in THOSE were flat-out wrong (not to mention that the customers wouldn’t have those anyway).
When I
@reppep – you are right … I did a poor job of explicitly typing together music skills with programming skills. I believe quality code is more an issue of structure and flow than spelling and grammar.
Spelling and grammar, to a coder, are things caught by pre-processing and compilation. It will fix your code but not your comments. Not necessarily and indication to sloppiness in the logic. The original quote was “Any relevance to code quality is purely accidental”, meaning spelling as an indicator.
You raise an excellent point about the availability of documentation. But I find ‘hacked on’ code far more prevalent in enterprise, where young (cheap) engineers are used to modify systems they have little understanding of. Even if the documentation is there, they seldom read or understand. Nor have I ever seen a functional specification in the module I was working on, only snippets of explanation.
It’s a red herring in that it moves the discussion from tangible metrics we used today to an arbitrary one that I have as many reference points to undermine the assertion as support it.
-Adrian
Adrian,
You never did explain the relevance of musical skill…
I see your point, but (perhaps unsurprisingly) don’t completely agree.
First, you say “Any relevance of human language skill to code quality is purely accidental.”
Well, that’s an overstatement. There are dumb people who are bad programmers and writers. There are smart people who are good programmers and writers. If you are, perhaps, a professional editor it might be able to judge writing skill than code quality, and there correlation between programing and writing skill is not completely random.
Second, even if you have good VCS when the code is written, someone may not have access to the complete repository in the future. If you stick the documentation in the source, it’s both harder to lose and easier to find.
Third, some shocking amount of code (especially in the open source world, but in commercial outfits too!) is later hacked on by someone other than the original author. I don’t recall the numbers, but they’re much higher than I would have guessed.
Revising clear code with good comments right by the executable source is easier than digging up supporting documents and figuring out how they relate.
Fourth, I do believe there’s a correlation between carelessness in written English (or whatever human language you use) and source code. I don’t know how strong it is, but I think it exists. This isn’t guaranteed, either. I have a dyslexic friend who’s a very talented and skilled programmer. His English composition starts out problematic, but (because he cares deeply about his output) he cleans it up. I don’t know what his source looks like, but whatever it looks like, it works very well. So his dyslexia impairs his English but not his programming, while his commitment and perfectionism affects both English and source code.
So it’s not a herring, but English writing skill is not as tightly correlated to programming ability as an English writer/editor might like. I’d think more closely than musical ability, but I haven’t done a study!