Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Has anyone defined a standard for reading code out loud, for any language? I imagine this is important to software like screen readers for the vision-impaired. This sort of thing also comes up when you are discussing code with someone, reviewing it in a group, or teaching a class.

In the C family of languages, there are a lot of words with "obvious" pronunciations. Some are simply English words: for, break, case, default, etc. Some abbreviations, like int, are unambiguous. And then there's char.

I always tend to say it (and hear it in my head) like the first syllable of "charcoal". It was jarring to me the first time I was talking about code with someone who pronounced it like "car", which actually makes more sense because char is really an abbreviation of the word "character", so clearly it should be pronounced the same. But even knowing that, char-as-in-coal feels more right to me.

And then there are statements like foo = bar ? *(++baz) : zardoz.

Has anyone anyone produced a document dictating the correct way (in their opinion) how to read code aloud? Either for a specific language or maybe code in general?

share|improve this question
9  
Reading Perl out loud ... <oh the pain> –  Rook Jul 5 '11 at 19:03
4  
Just for curiosity, why do you read code aloud? I think I never did it –  Vitor Jul 5 '11 at 19:07
1  
This would also be useful for dictating programs during the commute. Fortunately, being a Delphi program I would only dictate with extreme elegance. –  Peter Turner Jul 5 '11 at 19:16
2  
@Peter: Just out of curiosity, how do you pronounce := ? –  Mason Wheeler Jul 5 '11 at 21:01
2  
@Mason Fortunately, Colon Equals –  Peter Turner Jul 5 '11 at 21:08

4 Answers 4

up vote 14 down vote accepted

Quick coverall: read this great article at Coding Horror

Whenever I'm discussing code over the phone, I never read it literally. You have to "compile" it to human, and if there is still confusion on the other end of the line, you can move towards a more literal reading. For example, I'd read your example as

"If bar is true, increment the baz pointer and assign the value at that address to foo. Otherwise set foo to zardoz."

I've been a full time telecommuter since the mid-90's, so practically all of my interactions with my colleagues has been over the phone or other indirect means. Very often we're sharing either a screen (terminal) or VNC (X) session. Besides the regular camaraderie, we spend all day talking about code, design, planning, etc.

When we talk about code, we use jargon that is deeply tied to the type of project being worked. One of the (many) reasons it takes so long for a new group member to become fully functional is because they're essentially learning a new language each time they join a new department/company.

As I said above, and as others have said, we try to talk at as high a level as is appropriate for any discussion. But sometimes, you really have to just say to someone: "Type this"

How do you say it? Well, we could just give an enumeration like...

~  tilde
`  backtick
'  single quote
"  quote (or double quote)
/  slash, \ is backslash
#  pound or hash
!  bang (or exclamation mark)
@  at
$  dollar
%  percent or mod
^  caret or xor
&  and or bitwise and
&& and or logical and
|  pipe or 'or' or bitwise or
|| 'or'
*  value of, times, glob, multiplied by
() parens, open paren, close paren
{} braces, curlies, open stash, close stash
[] brackets, square brackets, at & sub (for subscript) (for C-ish arrays)
...

This are just how "we" say these characters. To get an idea of the entire range of saying "#" take a look at the wiki page for #

So there's too much variability. It has to be specific to the language that you're coding in (just as I'm typing this in English for our human communication).

Without the context of language you'd constantly have to revert to character by character spelling. So most folks I know of fall back to whatever the language standard calls things.

SELECT COUNT(*) INTO x FROM ...   (SQL)
X IS Y + 1                        (Prolog)
(setq x 40)                       (Emacs lisp)
/def x 40                         (PostScript)
x = 40                            (C)
$x = 40                           (Perl)

Each of those would be implied by just saying "Set X to ..." within the proper context. Don't even get me started on what code is read as "is string X equal to string Y".

If you say "hash bang bin bash" or "shebang bash", just about everyone will know that means "#!/bin/bash". If they don't they'll say, "Huh?", and you step it down a notch "At the top of the file: Pound sign, exclamation mark, slash, bin, slash, bash, newline". If they still don't get it, you step it down yet again: "See that keyboard in front of you? See the "3" key? That mark on the top when you press shift is a pound sign, that."

Bottom line:

  • don't worry about it too much, you'll be wrong, everyone will get over it
  • it's too specific to exactly what you do
  • always carry a towel
  • read the article over at Coding Horror
share|improve this answer
    
I agree. I almost never read the code "word for word" I just explain what it is doing. –  Joe Jul 5 '11 at 19:50
1  
Would your goal be to explain what is going on or to let them copy it down verbatim? –  Job Jul 5 '11 at 19:51
1  
@Job - If you're actually reading code, and not just explaining modules, classes, blocks, subs, etc, then you need a certain amount of specificity. But I would never try to type it with my tongue. Just think how hard it is to tell someone an email address or phone number out loud. If it really does come down to spelling it out character-by-character, then it depends completely upon your audience. If the tilde has to be referred to as a "squiggly", then so be it. –  Mark Mann Jul 5 '11 at 19:55
    
Mark, I agree with what you wrote (meaning often trumps literal accuracy), but it doesn't really address my question, which is really about the process of agreeing on matters like what to call a # or a !. You don't even say why you discuss code over the phone. Since you've got the most votes, could you flesh out your answer some more? –  benzado Jul 5 '11 at 22:11
    
I've accepted your answer, since in addition to taking the time to update it, you linked to Jeff Atwood's blog, which in turn links to the entry for "ASCII" in The New Hacker's Dictionary, which is pretty much the sort of thing I was looking for. Thanks! –  benzado Jul 6 '11 at 16:47

I've never run across any standards for speaking language syntax out loud. I have run across little snippets where someone has expressed their own personal preference for instance referring to "#! /bin/sh" as "Hash-bang slash bin slash S H" as opposed to "pound exclamation forward-slash B I N forward-slash S H" the later might assume the listener has less familiarity with the construct.

There is also a great disparity in the amount to which different languages are readable out loud. Take for instance the differences between Python which tends to be easier to speak out loud vs. say Perl which requires you to either say a lot of punctuation or translate from "$var[20]" to "the twentieth element of array var".

My own experience is that it's very contextual based on the reason for me needing to read the code out loud, the knowledge level of the listener and the language in question.

In the case of code reviews I'm more likely to explain a statement than try to read it out loud as it is usually more important to get the meaning or thought process across than just read the raw code to the listener(s).

When I'm trying to get someone to type an exact line of C code into an editor (for example I'm looking over a junior programmer's shoulder and see how to fix a line of their code), I often end up speaking code out in keywords and symbols such as "if space open-paren null double-equals p close-paren..." That same interchange with a more senior developer might start out more like "you need to check for p being null here..."

share|improve this answer

Talking about code is one of those times that pseudo-code becomes extremely handy.

If somebody starts giving me code by the character, then I'll just tell them to email it to me and I'll let them know what I think.

share|improve this answer

Short answer

The closest thing to a standard pronunciation guide appears to be the entry for "ASCII" in The Hacker's Dictionary (a.k.a. The Jargon File). It contains a table derived from "revision 2.3 of the Usenet ASCII pronunciation guide" which is no longer easily discoverable online. There is a relevant discussion thread, "Name that character!" on comp.misc in May-June of 1991, which credits Maarten Litmath as maintaining the original document. The thread notes that "cleverer" names such as "Donald Duck" for "&" were omitted from the newer document.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.