Sign In

Communications of the ACM

Kode Vicious

Literate Coding


View as: Print Mobile App ACM Digital Library Full Text (PDF) In the Digital Edition Share: Send by email Share on reddit Share on StumbleUpon Share on Hacker News Share on Tweeter Share on Facebook
flowers with code

back to top 

Dear KV,

Do spelling and punctuation really matter in code? I'm a freshman studying computer science at college, and one of my professors actually takes points off of our programs if we spell things incorrectly or make grammar mistakes in our comments. This is completely unfair. Programmers aren't English majors and we shouldn't be expected to write like them.

Miss Spelled

Dear Miss Spelled,

Who is your professor and can I please send him or her some flowers? Normally I find myself wanting to send people black roses, or a horse's head wrapped in paper, but your letter makes me want to send whoever is teaching you to code a big bouquet of fresh flowers, and a card, and maybe one of those ridiculous balloons that people now send as well.

While it is true that "programmers aren't English majors," there are daysmany, many daysthat I wish they were, or that they knew one, even tangentially, and offered to help with their science or math homework in return for some help making themselves better understood. The amount of code I have had to beat my head against because the original author did not make his or her intent clear in the comments, when there were comments, is legion, and all that head beating has given me many headaches. It cheers me to know someone else out there is beating your head for me, so maybe, someday, my headaches will go away. I also think the voices might stop at that point, too.

Clear code is actually more aligned with clear writing than most people are willing to admit. Many programmers seem to have gone into their field to avoid subjects such as English or anything that would require communicating with other people rather than machines. That is unfortunate, because code is a form of human communication.

Although a computer will execute your program, it will not execute it in the exact form in which you wrote it, and it definitely does not care that your variables are misspelled or that your comments do not make it clear who did what to whom in the code that follows them. Code is not just for computers; it is for other people as well. If the next person who reads your codein your case your professor, but after school it will be your workmatescannot make heads or tails of it because you failed to write in a clear manner, then that is sloppy work on your part and deserves poor marks.


Clear code is actually more aligned with clear writing than most people are willing to admit.


There are many defects that make reading code difficult: from poor structure, to poor formatting, to poor spelling. Attention to detail is the hallmark of all good coders, and that's not just detail in terms of the executing lines of code; it's all of the details, including the words you use and how you use them.

If you are a really poor speller, then run a spell checker over your code before you submit it; and if English is not your first language, then ask one of your classmates to read your comments and tell you if they make sense.

Remember, whether you like them or not, other people are going to read your code, and you owe it to them to make what you wrote easy to read.

KV

Dear KV,

I think I have now come across possibly the most stubborn and recalcitrant programmer I have ever met. He may even rival you in ability to complain about stupid things he encounters. While he's an amazing coder who can produce clear and elegant programs, he has one odd blind spot: he hates debuggers. I don't understand why, and asking him only gets you either a long diatribe or strange mumbling, so I've stopped asking. His preferred form of debugging is via print statements, no matter what language he is working in. While I understand that a debugger is not a replacement for writing good code, it's a tool I wouldn't really want to be without. Why would anyone choose print() over a debugger?

Bugged and Debugged

Dear Bugged,

I never understand why people who read my columns think of me as stubborn or recalcitrant. Despite my pen name, I am nothing but sweetness and light, and I never complainI simply point things out.

With that admittedly ridiculous denial out of the way, let's talk about debuggers and people who do and don't use them. Yes, there are people who find debuggers to be an inferior tool and who prefer to use in-program logging, or printf, statements to find out where their program is going wrong. I suspect you have also heard about people who cut their own quills and make their own ink for writing.

A debugger is a tool, and if the tool works for you, then you should use it. I see no reason to shun or depend solely on a single tool to help me correct my programsnot that KV ever has bugs in his code.

All that being said, there are many places where a print statement is what you actually want. It's important to remember that the debugger interferes with the program it is debugging and can lead to problems with observation. Armchair physicists love to talk about Schrödinger's cat, the thought experiment wherein observing an experiment has the effect of changing the outcome of the experiment. A debugger can have the same effect, and can be far more pernicious than the simple print statement. When you're using a debugger on a program, the debugger is introducing overhead, stopping and starting your program using signals, and generally manipulating your program like a sock puppet. While sock puppets are amusing, they're not subtle, and so subtle bugs may not show themselves when you're using the debugger.

A print statement, on the other hand, is a simple way to find out if something has gone drastically wrong with your code, and this is why good coders add logging to their systems almost from the start. I've even seen someone use print statements to debug multiprocessor locking in an operating system, by printing messages to two different consoles, one tied to each of the CPUs.

The biggest problems I see with using print statements for debugging are that they are often left active when they should not be, and in many cases, adding the print statements changes the layout of the code in memory. If you're looking for any kind of complex bugfor example, a memory smash, threading, or timing issuethen the humble print is more likely to cover up the bug than to help you find it. In these cases, you're better off with a good debugger and hardware that supports watchpoints. A watchpoint is a way to see if a memory location changes at runtime, and it is the best way to find memory smashes in your codethat is, bugs where you're accidentally overwriting memory.

As I'm sure you expected, KV comes down on the side of having many toolsfrom rough clubs and machetes to finely honed scalpelsfor killing bugs.

KV

q stamp of ACM QueueRelated articles
on queue.acm.org

A Conversation with Steve Bourne, Eric Allman, and Bryan Cantrill
http://queue.acm.org/detail.cfm?id=1454460

Kode Vicious: Gettin' Your Head Straight
George V. Neville-Neil
http://queue.acm.org/detail.cfm?id=1281885

Back to Top

Author

George V. Neville-Neil (kv@acm.org) is the proprietor of Neville-Neil Consulting and a member of the ACM Queue editorial board. He works on networking and operating systems code for fun and profit, teaches courses on various programming-related subjects, and encourages your comments, quips, and code snips pertaining to his Communications column.

Back to Top

Footnotes

DOI: http://doi.acm.org/10.1145/1859204.1859219


Copyright held by author.

The Digital Library is published by the Association for Computing Machinery. Copyright © 2010 ACM, Inc.


Comments


Andrew Fry

At the risk of violent agreement - source code has two main purposes. One purpose is execution leading to some actions. The other purpose is communicating (to humans) what the system does and perhaps how it is done (the system usually encompassing much more than computers).

For any program that is used over a significant period, communications is more important than the execution actions - the actions (which are probably wrong) will be updated and changed over time - but the communications aspect is necessary to update the program.

Please continue beating the heads of recalcitrant "programmers".


R Oldehoeft

Another vote for KV on literate coding. I had a long academic CS career, and can offer a few anecdotes:

* When I met with high-schoolers bused in to campus, I would tell them that they should study all the math, science, and ENGLISH that their school offers--not a popular message.

* I would tell my own undergraduate students that the most important programming language was English! If they are good technically, they will be required to communicate with other humans on a literate level--another unpopular message.

* I required a term paper in my programming class (after surveying them about languages they knew) about a language that they did not know, giving a wide list to choose from and providing a template about what they should report. One graduating senior, in turning his in at class, sighed: "That's the last writing I will ever have to do!" I just smiled, knowing that, from the second bullet above, he was probably right.


Displaying all 2 comments