Can we all agree, for a moment, that language is important?
No, not your favorite programming language. I mean human language – the way we communicate meaning and intention. It is important.
Without language, semantics and meaning, Apple goosing bubbles orange nerf solos te juggler with ducken butt, and warbles con queso; Am I right?
Code Is For Coworkers, First
First and foremost, code is for people. It may be for yourself, your coworkers or complete strangers using your code. But the purpose of code is first to convey intention to other people. Sending instructions to a computer is a distant second place.
Don’t believe me? Ok. Tell me what the intention of this code is:
Yes, syntactically correct code is important if you want the code to compile and run. But, writing proper syntax is easy. It takes no real understanding of language, intention or human interaction to write proper syntax (as illustrated w/ the obfuscated example).
Language Sets Expectations
The language we use conveys intention and creates expectations and perceptions.
This is true in human language – written and spoken – and equally true in code. The perceptions and expectations that our variable names, method names and other names convey in code can lead us down a path of understanding or confusion – largely based on whether the reality of the code we see matches the expectations of the language used.
In the above code, there’s hardly anything that looks like language… it’s mostly just random letters and numbers. Or what appears to be random letters and numbers.
But truthfully, the original code wasn’t that much more meaningful. It was just a simple object with no real meaning in it’s name, and methods that don’t convey a lot of intention. It was sample code to show correct syntax and obfuscation.
In reality, our code needs to convey much more meaning and expectation than this sample code.
Expectations Of An API
An example from a previous blog post shows intention-revealing characteristics of code in more detail:
This code has significantly higher value to anyone that reads it, than the previous chunks of code in this post. It is well-formatted with well-named objects and variables, and the intention is made at least somewhat clear – if not by the code itself, then by the comments.
With this code, however, I have a set of expectations and intentions communicated to me.
I see the “on” method of an object and I expect this to be an event system. I expect to put the name of an event that I care about as a parameter, and have a callback method to handle that event.
I see the “getEmployeeDetail” method and I expect it to somehow get the employee detail for me… shocking, I know.
Sure, there are failings in this code’s expectation set, too. If I didn’t know that “getEmployeeDetail” returned an object with events, I wouldn’t get that expectation from the method name.
Even with these failings, though, this code is infinitely more readable and relatable than the first obfuscated example, above.
The code that our computers run directly may not be understandable by humans, but the code that humans write certainly should be. Without clear and intention-revealing names and structures, we are left with an extremely difficult task when trying to work with or modify code.
Without language and semantics, we’re go3 d io34on 3n k9d93n o3nf;llk. And if we exclude meaningful language from our code, then our intention and understanding of that code flerp narffles the jars of qwerties.
So do yourself, your coworkers and your API consumers a favor. Write code that reveals the intentions by using names that are meaningful and conventions that express purpose.