Your code should be as readable as the user stories.
As a hiring manager, I often see candidates lose focus on an important aspect of quality code: readability.
It is cool to come up with the shortest one-liner solution. Sadly, it may not be a line of enjoyable code to read.
It is also cool to write the code with the most optimal big-O space and time. But if nobody else can comprehend it without a whole page of explanation, more than likely it is over-engineered. Of course, the core 1% of your software that runs a million times more frequently needs to be highly optimized, even that means giving up readability as the trade-off.
I am not saying the most efficient code is bad, or you should write crappy, slow, and verbose code. Readable code doesn’t have to be slow. There is a fine line between well-engineered and over-engineered.
Leetcode has a large set of well-defined questions, or user stories if you like. They have been used heavily in coding interviews.
I am going to use some of those questions to show what I mean by readable code. My focus won’t be big-O space and time, nor the length of the code. As a warning, the solutions presented here won’t help you score the highest if your interviewers are looking at testing you on those.
Why Readability is important?
I am smart. If you are also smart, you will have no problem reading my code!
A fun fact, 99% of the developers are not as smart as the top 1% smartest developers.
Then your company should hire the top 1% smartest developers!
Another fun fact, even you only hire the top 1% smartest developers, 99% of your teammates are not as smart as the top 1% smart developers in your team.
Storage is getting cheaper. Computational power is getting cheaper. But software engineers’ time is getting more expensive. If the one-liner “smart” code you wrote takes your peers twice the time to comprehend, and four times the effort to build on top of it, you aren’t doing your CFO any favor.
What is Readability?
There are many definitions of code Readability. Here is mine.
After reading the code, your fellow software developers can easily reverse engineering back the original product requirements. The more accurate it compares to the original, the more readable your code is.
What does that mean? Here is an example: 202. Happy Number
The shortest version I found online:
It works and works correctly as a solution to this Leetcode question. Without reading the original Leetcode question, here is my attempt to reverse-engineering the requirement.
Given a number, keep replacing it with the sum of the squares of its digits, keep track of it. If I have seen it, then stop. If the repeating number is a 1, return true; otherwise, return false.
Trivial difference: even the number is 1, it won’t stop until it sees 1 the second time.
How about this slightly longer one?
My attempt to reverse-engineering the requirement from that is:
Given a number, if it is 1, return true; otherwise, keep replacing the number by the sum of the squares of its digits. If I have seen the new sum, return false; otherwise, keep track of it.
That is very close to the original question.
But there is one logic that your peers may need to wrap their heads around. Why if it is seen, then return false? What if it were a 1, then it should return true, right? Don’t tell me that a 1 will never end up in the seen set since if the sum is 1, we will do that at line #8.
Oh, I see, if it were a 1, it would cause it to break out from the while loop in the next iteration. So that is, even we still add the 1 to the seen set, but we are not using the fact that the 1 being in the set to make any decision.
The most readable solution:
That solution is similar to the shortest solution above. The difference is, I resist the temptation to play smart by keeping those two lines (#4 and #5.) Everything is explicit now. Loud and clear. If you find yourself trying to make the code shorter by changing to implicit logic, or even changing the requirement to a slightly different “equivalent”, don’t do that.
Here is another example: 13. Roman to Integer
Here is a short version:
If we knew how Roman numeral works, we could actually work it out from right to left and do either plus or minus based on the comparison of the values.
Even though the question constraints include “It is guaranteed that s is a valid Roman numeral”, the question doesn’t clarify what a valid Roman numeral is. The only rules present to us are 1) to add values up, but 2) to watch out for those six instances where subtraction is used.
Or put it another way, the from-right-to-left solution based on some correct but not provided assumptions.
Here is the longer but more readable solution.
It can be easily reversed engineering back to the original Leetcode question.
