Most software engineers these days have taken at least 1 software engineering class in college to be able to distinguish between good code and shit code. If not, you’d hope software engineers care about their crafts enough to have read books like Code Complete to never name variables “foo”, or “bar” in production code. Sadly, this is not the case.
Many engineers, young and old, sometimes write “lazy code” and violate fundamental programming commandments, making refactoring miserable for the next engineer. Channeling my inner Martin Luther, I’ve created a Software Engineer’s 95 Theses, a list of the 3 most egregious coding mistakes that no engineer worth his salt should make. If you do any of these, you’re a bad software engineer and your co-workers probably hate you. Take a minute to ask Don Knuth for forgiveness and vow to never do it again.
1. Lazy names
All computer programs, like books, are written solely with words. Think about your favorite book. What makes it a good book? Take Harry Potter; it’s easy to read, is broken down into distinct and manageable chapters, and tells a fascinating and coherent story. Then compare this to a physics textbook that is littered with inadequately named variables and complex concepts that require multiple readings to understand; unless you’re Einstein, it’s a much harder and slower read than Harry Potter.
Good computer programs should read like Harry Potter; and naming plays a big role towards this end. Every author agonizes over choosing the right words for their stories, and software engineers should do the same when programming.
Come up with best possible names for your projects, files, libraries, functions, classes, and variables. Don’t abbreviate to save space. If you’re writing functions that look like “rstuc” (resetMicro), wake up, it’s 2017; you’re not doing the compiler a favor (most compilers can handle 31+ chars for variable/function names) and instead making life hell for your coworkers. Re-read your code and rename things to simplify the code as much as possible for the next person who has to read it.
2. Magic numbers
A magic number is the epitome of programmer laziness and a nightmare for code reviews. Unless you’re initializing something as simple as a loop counter, there is almost always a define (or a static const) for your magic number that will improve readability.
When replacing magic numbers with words, be descriptive and use uppercase for better readability.
3. Long functions
As a freshman engineer at Northwestern, I was required to take 4 quarters of Engineering Analysis; I solved fascinating problems involving dampers and trusses using MATLAB. For every problem set, I’d submit a single ~500-line-MATLAB file that consisted of a single function, and receive a satisfactory grade as long as my output was correct. The professors hadn’t bothered to tell us about classes, modularization, or design patterns, so I didn’t know any better. Readability? What’s that?
But as a professional software engineer, you have no excuse. If you’re writing functions longer than 200 lines, you’re not a software engineer — you’re a hacker. While there isn’t an explicit maximum for lines of code in a function, software engineers should modularize their programs and ensure each function is as simple as possible since long functions are more difficult to write, test, read, and debug.
The compiler doesn’t care whether a function is named “gt” or “getTemperature”, but your co-workers do; you need to internalize this idea if you’re serious about becoming a good software engineer.
Be a great teammate
Despite being the best player in the world at the time, Michael Jordan lost in the playoffs every year from 1986 to 1990. It wasn’t until 1991, when Jordan learned to trust and better utilize his teammates under the Triangle Offense, that Jordan won his 1st of 6 championships.
Similarly, software engineering is a team sport. Great teams consist of great software engineers that make others around them better by writing good, testable, and readable code every single day.
Consciously choosing to write good code is not convenient, but path to greatness is not easy. If it were, everybody would be great. So in the spirit of Michael Jordan, just do it.