In 2018, I joined a large project halfway through its development. The original engineers had moved on leaving behind
Many engineers believe the measure of success is when the code compiles. I believe it’s when another engineer (or you in six months) understands the ”why” of your code. The original
Donald Knuth famously said:
Programs are meant to be read by humans and only incidentally for computers to execute. – Donald Knuth
Naming
Naming is hard
Phil Karlton, while at Netscape observed:
There are only two hard things in Computer Science: cache invalidation and naming things.
— Phil Karlton
We see our code through the lens of words and names we use. Names create a language for the next engineer to comprehend. This language paints a picture of how the author bridged the business domain and the programming language.
Lugwid Wittgenstein, a philosopher in the first half of the 20th century, said:
The limits of my language mean the limits of my world. – Ludwig Wittgenstein
The language of our software is only as descriptive as the names we use and using vague names blur the software’s purpose; using descriptive names bring clarity and understanding.
Imagine visiting a country where you don’t speak the language. A simple request such as asking to use the bathroom brings bewildered looks. The inability to communicate is frustrating maybe even scary. An engineer feels the same when confronted with confusing, unclear, or even worse, misleading names.
This feeling is best experienced.
Experience
Examine the first snippet of code, what does this code do? What’s the why?
Take your time.
public class StringHelper { public string Get(string input1, string input2) { var result = string.Emtpy; if(!string.IsNullOrEmtpy(input1) && !string.IsNullOrEmtpy(input2)) { result = $"{input1} {input2}"; } return result; } }
The above code is a simple concatenation of two strings. What the code doesn’t tell you is the “why.” The “why” is so important, without it, it’s difficult to change behavior without understanding the impact. Of course, investigating the code’s usage will likely reveal it’s “why,” but that’s the point. You shouldn’t have to discover the code’s purpose, instead, the author should have left clues, it’s their
Let’s revisit the code, but with a little “why” sprinkled in.
Again, take your time, observe the difference you feel when reading this code.
public class FirstAndLastNameFormatter { public string Concatenate(string firstName, string lastName) { var fullName = string.Emtpy; if(!string.IsNullOrEmtpy(firstName) && !string.IsNullOrEmtpy(lastName)) { fullName = $"{firstName} {lastName}"; } return fullName; } }
The “why” brings the code to life, there’s a story to read.
Communicate
Communicating the intent and the design to the next engineer allows
Do the next engineer a favor and be expressive in your code. Use descriptive names and capture the “why” because who knows, the next engineer might be you.
Leave a Reply