Standards for reading code out loud?

Question

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?

Answer 1

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

Answer 2

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..."

Answer 3

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.

Answer 4

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.