Describing Code in Ordinary Language
If code is a language, then it doesn't translate to English very well. Yes, it mostly uses English words, but not the way most of us understand.
I can code, and I can talk, but for some reason I have trouble talking about code. It's as if another part of my brain does coding. When I'm coding, I'm in some sort of symbiotic communion with my computer. My fingers type in characters in the right order and I see visual results on the screen. I'm not just in communion with my own computer, but with millions of other people on their computers, and with all the text that they have typed in over the years.
I'm plugged in to another dimension, communicating with another entity. Like in a William Gibson story. Or a dream. Like a dream, what is completely real when you are there is so very difficult to put into words when you wake up.
So back to trying to talk about code. I have wanted to describe what I have been working on lately, mostly because I think it's kind of nifty and I wonder if anyone else would find it useful. But what exactly is it and how on earth to describe it?
Even the terms 'application', 'process', 'system', 'file', 'record', 'table', 'import', 'server', 'map', 'array', key' and 'program' seem slippery and vague. Computer terms don't seem based in the world of objects. I realize that when I'm coding, I don't use these words, either, but work with concepts instead. The problem is in the act of turning these dream-like concepts into the inadequate collection of words that we are given.
I find this same difficulty when I try and read explanations of code. The words seem to bounce off.
However, there appears to be an optimum balance of words and examples that seems to really work. I'm thinking in particular of that vast compendium of knowledge, W3Schools.com. For some reason, their explanations always make sense. I can churn through zillions of other explanations on blogs and Stack Overflow and get completely befuddled, then a single page on W3Schools will lay it all out, crystal clear.
I think the trick is including just enough English language to allow the code examples to tell the rest. They always have a little green 'Try it Yourself' button so you can see how it works in real life., and use descriptive terms instead of abbreviations. If I search for help with PHP and land in PHP.net, I might as well be on Alpha Centauri, but W3Schools is like the nice teacher who explained algebra so that you could understand.
Maybe one day we will be able to converse about floogles and priffleclobbing our brommits, but until then, I will have to make do with 'superglobals' and 'exploding' arrays. Ack!