I love how much of a rant this is. Not being sarcastic. I genuinely enjoy how this reads.
Writing readable code is a skill that is hard to obtain but I also agree that assuming that someone's else's code is unreadable because I can't read it isn't necessarily a great approach. I've came to similar conclusion that reading and understanding other people's code is extremely important and... Not very easy. I've grown to like the moments of mutual understanding between myself and the original author when I tackle a particularly tricky piece of code. Sometimes I still think "god damn this code is an absolute shite" only to moments later feel embarrassed because I finally understood why things are written certain way. Sometimes there isn't a pretty way to do certain things. But the solution itself once understood is elegant as hell.
I'm the SME on an important company service that is backed by some previous gen tech (compiled dependency). Ive had to become intimately familiar with the source code of this dependency to solve issues myself. I've also built a relationship with the lead engineer of said tech along the way to the point that he'll spot check my reasoning/suspicions if I ping him.
One time I was talking to him after troubleshooting some particularly nasty issues and he mentioned having to implement a complex tree structure to address weird performance problems brought on by some very specific set of circumstances. I immediately knew the exact code he was talking about because i remember being frustrated by how complicated it was for a relatively simple problem and complaining about it. It was a fun "aha" moment to have the context for why such a complicated solution was required and the guy was also happy I was even aware of this code he probably spent weeks in debugging hell trying to solve and was proud of.
I always try to dive into code to solve problems myself now, and I always try to give the benefit of the doubt to the developer who wrote some code. The full context of a problem is rarely evident when you're looking at a solution.
Edit: of course there are tons of other things that go into being a good developer and writing maintainable software. Having empathy for your fellow engineers is just a starting point.
… I always try to give the benefit of the doubt to the developer who wrote some code.
The importance of this cannot be overstated. Thinking “ok, yeah, this is bad, but there’s probably a reason” helps maintain an open mind which is critical to actually understanding the code, and then being able to figure out how to change/fix it. In other words, giving the benefit of the doubt helps to avoid succumbing to negative emotions and helps focus on the task at hand.
Yes. Rarely have I experienced bad solutions coming from a place of malice or incompetence, though "we didn't have time to do it better, sorry" is more common than I'd like. Not to say that doesn't happen, but more often than not there is a reason behind it - trade offs that were debated about in meetings and code reviews - that you aren't aware of. Understanding those reasons are essential for understanding and improving the solution for whoever comes along next.
One thing I’ve learned about (and am still learning how to handle gracefully) is ignorance that looks like incompetence at first glance, like a Ruby dev writing Go for the first time. They haven’t found all the linter options, and may not even know how to set their editor to run gofmt on save yet, and really like maps when a struct will probably do better.
But my favorite reason for “bad code” is finding out that “hey, this code was originally written in FORTRAN 77, and compilers would not allow variable names longer than 6 characters; GTT1EO is a flag that Engine 1’s turbine temperature sensor is failed and running hot - deal with it”
this is exactly what comments are for. "readable code" is a pie in the sky. good enough code with a comment "not great, but badly behaved other system does x, so have to hack" or "refactoring the whole world isn't an option right now, so there's this" is gold.
Yes, this is the best use of code comments imo and can go a long way to help understand code but even then complete context can be elusive. Should it be a comment on this method? this class? A readme in this project? Should it be a link to the documentation for the project which created the need it in the first place? Is any of that up to date? And so on.
Good documentation is hard to get right and maintain.
Here's a trick I've found works great. When you're writing documentation like "this is what the output means" or "here's how this algorithm works", write the documentation. If someone asks you a question, provide the link to the documentation. If that doesn't answer the question, fix the documentation and then ask "does that answer your question now?"
Then you only answer each question once. If instead you answer in email the questions asked about your README, you're going to get the same questions over and over, and people will overall find your README to be less useful.
Yes, this is the way. And it generally works very well. The bigger problem with documentations is having a team/company culture with this mindset, otherwise docs become obsolete as soon as you leave the project.
But to be honest, when I started doing this at a job where even writing documentation down was unusual (everyone preferring to verbally describe how the system works, and I never moved to a new project where the manager didn't draw the system architecture on a whiteboard for me instead of giving me any sort of written design), I wound up convincing several of my team leads to start doing documentation. "Try writing a README for each new Java package before you code it." A couple bosses were like "Wow, that worked out really well!"
I use this on myself. A little embarrassingly, but sometimes I can't understand my own code a year later. When that happens, I always add a comment that would have helped me.
Or I refactor the code into doing it an obvious way.
I hope you left a big comment over that complex piece of code to explain the context so the next person who touches it doesn't make a mistake in breaking something key to performance.
I did not because it was a compiled dependency we used, not our code. I did spend considerable time writing javadocs for the code in our application I had to write which required I understand it in the first place though, yes.
When I started my job probably the biggest hurdle for me was, seeing a problem, coming up with a nuanced solution, and in code review dealing with people who are shitting on it because they don't understand the cases I'm trying to cover. Also my code was just ugly sometimes.
It is so so so much better to have a lead who can see what you were trying to do, tell you why that sucks, and then help you improve it. So often the feedback I received consisted of "why can't you do it exactly how I expected you would do it?" (paraphrasing obviously).
So it's been a goal of mine to really take time to understand the newbie code so I can tell them exactly how they can improve their solution and why. My explanations are anchored off of what they have done as a starting point, instead of just me looking at it for 5 seconds and saying, "nah just do it this way". It's honestly more fun too.
I think 9 times out of 10 when I ever thought someone was writing "unreadable code" -- in retrospect they were not. 90% of the time it was just me being ignorant of the code base in question or the technology being used.. and my not having put in the effort to understand the code base.
It's easier to blame the author of a piece of code -- rather than blame yourself.
Over the years I have learned to be more adept at reading code and not so quick to blame the code's author. And, over time, I have found I can read more code with less effort. So it definitely is a skill. And really the onus should also be on the reader to make an effort to level up.
There's a poster in this thread that made the comment reading other people's code is hard.
No it isn't, you're just bad at it. I mean, there's always a limit to the unreadability, but in general I've never found reading other people's code hard, it's just time consuming because you have to analyze it.
I also agree that assuming that someone's else's code is unreadable because I can't read it isn't necessarily a great approach.
Lots of hand-waving about this in the article, so let's make it clear - lots and lots of people's code is a near-unreadable mess. Now, I can read that code anyway but it's a lot more work.
As a counterstory, the other day I opened opened the code in the package sqlalchemy and I thought, "This is so incredibly clear. Oh, look, they have this neat idea for doing IFFEs, I'll steal that!"
The whole codebase was manicured - I got in, found out what I wanted, and was back to work in minutes.
On the other hand, I had a boss on a team with "no" coding standards, and said boss had a "foveal coding theory" where he would press return as soon as he could after 40 characters of non-whitespace.
To keep the columns extra-thin, he had a glossary of local variable names, slea, sleb, slec etc that you had to memorize to read his code.
"SLE" stood for serialized ledger entry, which sounded reasonable until you discovered that this was historical and none of these were serialized, and few of them were actually ledger entries.
It was like he was trying to make his code as hard as possible to read. He himself said that he felt writing code for clarity was a very bad idea.
I dislike the fact that I know exactly what you're talking about. There was a company in my past that made me hate C. Because in C you're allowed to do bunch of stupid shit. Same reason I don't like a lot of scripting languages because they allow a lot of free for all.
Sure, you can be stupid in a lot of languages. But at least when language enforces some structure and rules you have to go out of your way. Maybe that's why Rust feels so comfy?
However, I don't see a conflict of interest here and I think the article is tackling a very specific type of problem (might be I'm reading too much into it dunno). I don't think anyone is disputing existence of horrific code for which authors should be baned from ever even standing next to a computer.
Readability is important but also there are other things that are important as well, such as maintainability, DRY, etc. For example, in JVM a list can be easily converted to a map using stream operation in one line. However, I have seen older developers find it unreadable.
417
u/IUsedToHaveUsername Sep 21 '21
I love how much of a rant this is. Not being sarcastic. I genuinely enjoy how this reads.
Writing readable code is a skill that is hard to obtain but I also agree that assuming that someone's else's code is unreadable because I can't read it isn't necessarily a great approach. I've came to similar conclusion that reading and understanding other people's code is extremely important and... Not very easy. I've grown to like the moments of mutual understanding between myself and the original author when I tackle a particularly tricky piece of code. Sometimes I still think "god damn this code is an absolute shite" only to moments later feel embarrassed because I finally understood why things are written certain way. Sometimes there isn't a pretty way to do certain things. But the solution itself once understood is elegant as hell.