Documentation – Enforcing Programming Standards for Shared Libraries

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

The main concern (I have a similar problem with my job) is that if "The Process" demands that you deliver certain artifacts at certain times, and no one is allowed to challenge the almighty "The Process", then if you try, you will loose! It's not just a simple matter of it being a better way (Which iterative doc development is).

So what you need to do is work within the process, but find a way to work the way you want to as well. For instance, does your process allow document modification once submitted? If not, then no iterative develpment is possible. If so, then you need to think about the cost of delivery (In terms of your time, your credibilty etc), and manage that cost. If, for instance, its a file copy and nothing more, then go for it. If (like me) it's a peer review, revision release, impacts dozens of people and costs thousands of dollars, then think carefully and make sure the new document really adds value.

A common way to work is a bare essentials, minimum document that meets the needs of "The Process" at the start, followed later by a final "as built" update that not only reflects reality, but has the details where needed, and is brief where the code speaks for itself.