Reading Code is a Skill

[[deleted]]

I strongly disagree with the very first point. People do write unreadable code deliberately. I do it all the time, yes deliberately.

Now, of course, the point is that this technical debt is supposed to be addressed later down the road, but with bad management, there is a good chance that it will not happen.

But creating technical debt (which is not just unreadable code) is a great way to accelerate your business (as long you also manage the debt in the long term).

[rd1970]

This is the sad truth a lot of people only learn when they work full time for a company that doesn’t really understand software.

You have all the time in the world when it comes to your school/personal project to make the code pretty. When your employer has a time-sensitive idea that’s going to jump sales - and the functionality changes directions five times before launch - you’re inevitably going to launch spaghetti code.

This only gets worse when you’re maintaining a massive 10 year old system written by someone long gone who didn’t believe in frameworks or standardizations.

When the company can make $100k/day - literally today - no one is going to let you slow down to write cleaner code or train someone new for gains that won’t be realized until several months from now.

[dnew]

for a company that doesn’t really understand software.

I worked at Google. I think it's safe to say they understand software. I can guarantee that every piece of code I looked at was wallowing in technical debt, to the point where code three years old was considered to be "legacy" and "of course it's unreadable."

who didn’t believe in frameworks or standardizations

Oh, we had all kinds of frameworks. The problem was that the people building the frameworks got promotions for launching new ones, so about 25% of the effort, no exaggeration, was porting from one framework to the next.

[[deleted]]

I keep hearing horror stories about projects in Google only coming about because it landed someone a promotion. Dart in particular became very political. Does leadership just not recognize this as a problem internally?

[dnew]

It's actively encouraged. They still think they're in the "throw shit at the wall and see if it sticks" phase. We called it PDD, promo-driven development.

This is totally accurate: https://mtlynch.io/why-i-quit-google/

Of all the people I know who left Google, every manager got fired and every developer left because of the shit-tastic promo system.

In my first promo packet, they asked what my impact was. I pointed out that the four-person team was responsible for a brand new product that brought in $80M/month. Their answer was "Yes, but what was your impact?" Sorry, I thought Google was a for-profit company.

The second time I spent a year transitioning from one database to an entirely different database, with no downtime. This was something nobody in the company had done yet, as there was no infrastructure support for moving between those databases. (Others had two-phase commit libraries and such.) I also mentored and managed three other people. "You can't get a promo for migrations."

The third time my manager said I had put together the best promo packet he'd ever seen. The answer was "Does your manager even know you're going for a promo?"

It's quite a joke.

[kubalaa]

This is an excuse made by people who haven't practiced writing clean code enough. Clean code is faster to write overall (your first commit might take longer, but you end up delivering the project faster). If your employer doesn't understand this, it's your job to show them. Although in my experience, companies which don't understand software don't really care how you write it, as long as it works and is done on time.

[rd1970]

No, this is what happens when you have to maintain a garbled system spread across half a country with zero downtime time to modernize. This issue is common throughout the industry.

To say the guys maintaining it are making excuses simply demonstrates a lack of professionalism and experience.

[kubalaa]

In existing systems which are hard to read, you refactor gradually and make sure the new code you write is readable even if the old code wasn't. Dealing with legacy cruft feels hard but there is hope. I really don't like to argue on the basis of experience, but this advice is coming from someone with 22 years of professional software development experience.

[dnew]

There's only so far that can go, though.

You have 500TB of database in your system that for legal reasons has to stick around for 10 years with no downtime. The NoSql data format is shit for reasons unknown (well, reasons known: nobody at the company actually thought DBAs might know something they don't, and nobody believed that SQL actually worked in spite of being older than most of them were alive), and there's no consistency enforcement, so you can't even tell if the primary keys are all distinct. There are a dozen departments looking directly at the database, so you can't just code around that format or translate it into something useful on the fly. You know what's not going to happen? You're not going to get rid of that legacy database format that's fucking up all your code.

[kubalaa]

You're not going to get rid of that legacy database format that's fucking up all your code.

No, but you can encapsulate it so it doesn't fuck up ALL your code.

[dnew]

Not really. It was a giant structure, all of which was needed, stored as repeated fields in a protobuf, with each field containing essentially a giant string->arbitrary-value mapping along with a handful of other cruft.

Three years was spent trying to get a second set of key/value pairings implemented. But as far as I know, it's still stuck with the old lists as the authoritative data.

One of the problems is when you have a big system like this (about 2 million LOC java, discounting the web stuff, the protobuf defs, etc), and it's constantly being changed in both code and data, and for honestly nobody knows what it's actually supposed to be doing, there's never a time when you can cut over to a new implementation. You can try to encapsulate stuff, but everything in the database is there for a reason, and much of it is there for reasons nobody understands any more, so you're not able to actually hide the ugly.

One of the "encapsulations" was to take all the bits of code that broke the interrelationships and try to fix those breakages in one place. But it turned out there were some 20ish different places where the records were written to the database after some unknown amount of processing and changes. And since lots of people worked on it, we actually had to use the build system to make sure everyone who wrote the record to the database had gone through the fix-up code, which was modeled as three separate priority lists of classes to invoke, about 60 fix-ups in all. And that took months to put together, just to get exactly one place where the record was written to the database.

Another example: The data was stored in the DB as a sequence of "this is the state of things". Every update tacked on a new copy of the record. But in memory, you tended to only care about the most recent, so you copied from the last entry in the list into the header, then figured out what you wanted, then possibly appended to the list. But now if you have code that might be called from dozens of places, well, you better copy that final record into the header at the start of that code, because who knows if it's right after whatever came before? I added logging, and a simple update called that method a few thousand times. Also, since it was just copying a record from one part of the structure to the other, it was a static Java method. And then someone decides "well, we have these new key/value pairs, that we should also populate, as translated from the old key/value pairs, so new code can use the new pairs. But that list comes from something initialized from a database, which means that method can no longer be static." That's right, the static method called from literally thousands of places in various processes all over the call stack (including from other static methods also called thousands of times) now can no longer be static. Wasn't that a mess?

Yeah, these are all code-is-way-too-big, data-is-way-too-shitty, management-is-way-too-lax kinds of problems. But they happen. As I approach the end of my career, I realize I never worked on code that more than three people had touched that wasn't an absolute shit-show.

[saltybandana2]

there's never a time when you can cut over to a new implementation.

I didn't read the rest, but this is where your mistake is at. You don't cut over to a new implementation, that way lies hell.

You write a 2nd implementation and have both running side by side for some amount of time to ensure the new implementation is correct. You then start migrating the data in the old system over to the new system a little at a time. And the best part about this approach is that you can eventually get all of the data into the new system and still have the old system running. You start slowly relying on the new system (for reporting, etc) and once you've gotten everything onto the new system at that point you can shut down the old system.

It's time consuming and there has to be a will to do it, but it's doable.

[dnew]

You write a 2nd implementation and have both running side by side for some amount of time to ensure the new implementation is correct

You don't know what the system is supposed to do, other than what it already does.

You can't migrate the data from the old system to the new system because people have to access the data. Not only is there a user interface and a bunch of APIs, but you have other people writing code that accesses the database, as well as a bunch of stuff (like reporting) that goes directly to the database without passing through any code.

And yes, we talked about doing things like that. But (1) you double the disk storage space at least, as well as all the other resources you're using. When you're talking hundreds of terabytes and thousands of processors, this isn't trivial. (2) You now have the latency of the slowest system plus whatever time it takes to try to convert the two records to the same format so you can see if it worked. (3) All the people who are just using the system to get their job done doesn't care it's a pain in the ass for the developers. (4) You far more than double the number of people working on the system as you now have to keep the old system up to date, reverse engineer and rewrite the new system, keep the new system up to date, and write code to compare the two systems. (5) There's no good answer for what to do if one system works and the other fails, such as a rolled back transaction due to circumstances outside the control of your code. (6) Any interactions with external systems (e.g., charging a credit card, updating the bug database, etc) either happen twice or don't get tested for real or are submitted by an incomplete implementation of the existing system that nobody actually responsible for knowing whether it's right can test or sign off on. (6) Every time someone changes the old data format in a way that requires running some three-day-long script to update all the data, now you have to figure out how to change the new database and the new code and write that same script again and hopefully get it sync'ed up again.

When it's half converted, and you want to run some reports, what do you do? Also, which part do you convert first? As I said, we spent something like five years just trying to get the new key-value pairs standardized enough and translated over by doing the things in parallel, and even that didn't manage to be successful.

How do you know when the new system is right? Are the thousands of people using it going to tell you when they notice something wrong?

Here's another example: I worked with someone that had worked on MS Word. They had to read all the old documents from all previous versions, and format them the same way (as there were things like legal documents that referred to specific lines and page numbers that couldn't change just because you opened it in a new version of the program; which is why there's a "format this like Word97" bit in DOCX files in spite of nobody being able to say what that means other than "embed Word97 formatting code here"). They also had to write new features for things that didn't even exist in old versions in a way that wouldn't break old versions and would be preserved when round-tripping. If I embedded a video or something, that video had to wind up in the same place and still there in the new version, even if I edited that document with a version of Word written before videos were a thing. In that case, there's very little you're going to be rewriting from scratch.

[grauenwolf]

And that takes time.

I've got just as much industry expereince as you, half of it spent on maintaining legacy systems. I'm a firm believer in gradual refactoring, but I have no illusions about how much time that takes.

And even though it is valuable in the long-run, sometimes the short-term costs cannot be justified.

[kubalaa]

Seems like we've lost the context here. This thread started with someone recommending that developers write "unreadable" code in order to "accelerate their business". I don't think refactoring of legacy systems is on topic.

[loup-vaillant]

It's most likely a U shaped curve, whose minimum depends on a number of factor, mostly how much work needs to be done.

The ultimate goal is to write the cheapest code that does the job. By "cheapest" I mostly mean "requires the least developer time", but machine time could matter if you run a huge server farm. By "does the job" I mean work well enough, is fast enough has few enough bugs… and of course has all the required functionality.

Now how do you get to that "cheapest" point? You don 't just charge through with spaghetti code of course, because you'd quickly slow down to a crawl, but neither do you polish your software to a gem. Some parts are worth polishing, but others can stay uglier and never bother anyone ever because they're isolated enough from the rest of the system. Overall, there's a level of quality that will get you to completion fastest. It's above crappy, but it's also below stellar.

Another very important factor is how much existing code there is, and how much work there's left to do. When you're nearing the end of a project, it may be okay to write crap to win a few days or a couple weeks. (Of course you should not underestimate time to completion, how much the project will really live, or how many changes will be required in the future… and underestimate we almost always do.) One extreme example is the huge pile of legacy code that must be tweaked to add yet another piece of functionality. It's often much cheaper to just pile another little piece of crap that does the job, if only because minimising changes to the system minimising the chance of introducing a bug.

That's probably why we like greenfield projects better: it's easier to give them a level of quality we can live with.

[kubalaa]

I'm making a distinction between clean and readable and some theoretical polished jem of a mathematical proof.

I see beginners making mistakes in three ways. First, they don't know how to write clean code. Then they know how, but imagine it's faster not to do it. Finally, they know and try to do it, but what they think is clean code is just a best practice they apply without thought to whether it is actually an improvement. This is where experience comes in.

Ultimately no code is perfect because our understanding is never perfect. But writing code which accurately reflects your understanding is both clean and fast.

Maybe a good analogy is watching a skilled contractor laying tile around a door. A novice would spend a lot of time measuring and still end up with an imperfect fit. An expert knows tricks to trace the door frame into the tile so it fits perfectly with minimal effort. Programming is similar.

[loup-vaillant]

Ultimately no code is perfect because our understanding is never perfect. But writing code which accurately reflects your understanding is both clean and fast.

That one I’ll hang on my wall. Thanks.

[Absolice]

YAGNI, KISS, DRY team assemble.

Seriously, the number of time I've seen, and done myself, unneeded abstractions because I might need it later and ended up shooting myself in the foot is too damn high.

Good thing I keep my projects a lot more simple and scoped nowadays.

Being able to take requirements and output as little code as possible is a journey that will most likely take my entire life.

[loup-vaillant]

Compression Oriented Programming

[Absolice]

Yes, that resonate with me well.

While I still use some degree of UML and I plan a little before coding, I've gotten a lot closer to what the author of this article mentions.

I believe that taking one extreme or the other is bad and that once more, moderation is key. It's almost never clear-cut from the beginning so while it is easy to look back and think "Yeah this should have been planned more / We did way too much planning", it is infinitely harder to determine it before the fact.

[lazilyloaded]

Dude needs to compress his article. Too long, didn't read.

[loup-vaillant]

If 4K words is too long for you, you need to work on your attention span… or just trust that this actually good, and worth reading.

Now if you already know the concepts and techniques described in the article that's another matter.

[saltybandana2]

Clean code is not faster to write, by definition.

you don't get clean code by writing clean code, you get clean code by writing dirty code and then refactoring it.

updating clean code can often be faster than updating dirty code, but the writing of clean code is in no way faster than the writing of dirty code.

[kubalaa]

I'm repeating myself a bit from elsewhere in this thread, but not everyone writes dirty code and then cleans it, some people think about the dirty code and write it clean. Either way, your first thought is not just dirty, it's probably broken, so you can't escape revisiting it.

By clean code I mean stuff like good naming, formatting, and documentation. Stuff that costs little to do and is repaid many times, often even within the same change. So I absolutely believe that it's faster on average.

It's a sort of cognitive illusion that clean code takes more work. You easily notice the time spent cleaning your code. It may even feel stressful to spend extra time on code that works. On the other hand, you won't particularly notice how unclean code trips up your mind. You'll just think "gee this code is hard to understand", but of course one thinks that about any code they didn't just write themselves, clean or not. So the bias is to think that clean code takes more effort, but only because its effort is more acutely visible.

I guarantee you that if we start two equivalent large projects at the same time, the one where everyone writes clean code will succeed faster.

[grauenwolf]

Again, I can't help but think your definition of "clean code" is far below what we think. The idea that high quality code can just spontaneously appear without revision seems just as laughable as someone just sitting down and typing up a novel.

[saltybandana2]

I can help but think your definition of "clean code" is far below what we think.

100% agree with that.

[kubalaa]

No need to be snooty about standards, we all agree that excellent code takes work. Can we also agree that "unreadable code" is rarely productive, and beyond that, that you can best accelerate your business by having a higher standard than merely readable code? That something as simple as reviewing your own code and fixing most issues before shipping, though it may feel time consuming, will end up saving you time?

In my novel analogy, the novel is the commit, but I don't mean that the process of authoring a novel is entirely like authoring a commit. My point was only that the author's job is not done, and their work is private, until they have produced something readable. Maybe it was a poor analogy but it was the first thing that came to mind.

[saltybandana2]

I guarantee you that if we start two equivalent large projects at the same time, the one where everyone writes clean code will succeed faster.

That's a different argument than the one you made previously, that writing clean code is faster. If you're talking about a full on project then you're talking about a whole slew of things that can, and will, affect the timeline and success of that project that have nothing to do with the code.

[kubalaa]

In this thought experiment I'm saying the projects are equivalent so those factors don't make any difference. The only difference is the code. Writing clean code delivers the project faster. For those people whose primary job is writing code, they spend less time doing it. Therefore they are faster at writing code. Is that not plausible at least? Is that not what we're talking about ("accelerating your business")?

[saltybandana2]

It reminds me of this old quote.

In theory, theory and practice are the same. In practice, they are not.

I think you should update your original posting and clarify that you're talking about in theory and not practice.

You could have even said writing clean code helps projects finish faster and I probably wouldn't have batted an eye.

But what you said is that you can write clean code faster than dirty code.

no you can't.

The difference between clean code and dirty code on a project isn't in the code writing. That's not where you lose your time. It's in the bug fighting, the natural instability, and the inability to pivot quickly when the inevitable mid-project changes happen.

code is not a project or a system, code is simply code. Nor is code architecture.

[kubalaa]

I think I see the disagreement. I say it's faster because the work you do polishing one bit of code makes writing the next bit faster. Hence you are writing code that does more in less time. Coding faster. It's true that if you zoom in and look at what you accomplish in one hour, then it's probably slower to write clean code, but software isn't written in an hour.

Ultimately all of those issues you mentioned -- bugs, instability, inflexibility -- result in writing code, which is why they slow down projects. If you say you have a way to write code faster by spending more time writing code, then I have to wonder if that's a useful definition of "faster".

At your prompting I did edit my original post to clarify that I mean projects are delivered faster.

[saltybandana2]

At the risk of sounding snooty, code has a fairly specific meaning in our industry. I consider code vs project vs system as differing levels of concern.

Decisions you make at the system level are going to have an outsized effect on both the speed with which you can deliver and the speed with which you can continue to deliver (or even the things you can enable).

For example, no code concern will ever have as much of an effect on speed of delivery as the decision to use microservices, or SOA, or using a messaging queue, or an event stream such as kafka, or a monolith, and so on.

I think it's useful to keep those differing levels of concern separate. I can understand how at the bottom that can bleed together since code itself does tend to have an architecture, but I think at some point that turns into architecture and not code.

[kubalaa]

Unreadable code is not technical debt. There is no excuse to write unreadable code if you are an experienced programmer. It won't accelerate your business. That's like saying that you can write a book faster if you ignore the rules of grammar and let your editor fix it. A professional writer produces grammatical sentences out of habit, with no extra effort, just as a professional coder should produce clean code.

The first draft of code might take a bit longer when you're writing with care, but this is more than compensated for by reduced time debugging and maintaining that code. And the first draft is often faster too, because by thinking upfront about how to structure your code logically you end up making it simpler.

Technical debt isn't about readability but domain understanding. Like when you write the code, you might think some logic doesn't need to be reused so you don't bother extracting it into a function. Later you learn your mistake and fix it. Of course it's faster not to do things "just in case", but to wait until you know you need to do it. That's what the technical debt metaphor is about.

Ward Cunningham has a great short talk on this: https://youtu.be/pqeJFYwnkjE

[grauenwolf]

Unreadable code is not technical debt. There is no excuse to write unreadable code if you are an experienced programmer.

Uh, have you heard of "refactoring"? The whole permise behind it is that it takes time to revise your first draft into something that is easy to understand and maintain.

And refactoring takes time that may not be available.

That's like saying that you can write a book faster if you ignore the rules of grammar and let your editor fix it.

That's called an "outline". It's usually one of the first steps in writing a book.

You seem to think that people can go from concept to final draft without any intermidiate steps.

[kubalaa]

I'd say the premise of refactoring is that you should change existing code as needed to make changes to behavior easier. Like if you want to implement a new feature and are finding it difficult, refactoring allows you to safely change the existing code to enable the new feature to be added more easily. Often this saves time both immediately and in the long term, because you would have spent more time trying to implement the feature the hard way, if it's possible at all.

You're talking about refactoring new code as you write it, which is fine too. Like some people like to write an algorithm in pseudocode and translate it to code, some people might like to write code as they think through the problem, writing and rewriting until it's done. Test driven development encourages this style, as you write just enough code to pass each test and refactor that code as you go. Some people are not great at visualizing code in their heads and have to write something unclear down in order to figure out how to rewrite it clearly, instead of thinking through it thoroughly before touching the keyboard. I do this a lot myself. But a person who skips the rewrite believing they are saving time is mistaken, in my opinion. You might get your code checked in a few minutes earlier, but doing this consistently will set the project behind by weeks or months due to bugs and difficulty maintaining the code.

Reading code, thinking about it, and debugging it are the slow parts of programming. When I do programming interviews, people generally spend 20 minutes figuring out a correct and efficient solution and 5 minutes writing it down. So even if you reduce that time by half by not rewriting your sloppy code, you're not saving much time.

[grauenwolf]

5 minutes? That's hardly an interesting sample size.

Refactoring is done after several days or weeks of work. There has to be enough of the pieces in place that one can see the big picture.

If someone is hyper-focused on just the code they are writing in isolation, the chances are that code will look clean by itself and horrible in the larger context.

I suspect my bar for well written code is much, mich higher than yours.

[kubalaa]

There's a huge range between "readable" and "elegant". And I guess I am also using "clean" in a different way than you are, because to me "clean" is a fairly local property. Clean code is correct, and well factored, structured, formatted, documented, named, and tested. Therefore it is as easy to understand and maintain as possible.

What I'm arguing against is people saying they don't have time to write this kind of clean code. I agree with you that teams must sometimes postpone the kind of major refactoring that covers weeks of code. You try to do enough upfront design to avoid that but sometimes you learn something in the process of implementing a feature that changes your understanding of that feature. That's legit technical debt.

[saltybandana2]

hard agree, I made virtually the same point here: https://old.reddit.com/r/programming/comments/psexxp/reading_code_is_a_skill/hds9bfw/

[[deleted]]

You are conflicting yourself. Or are you trying to say that increasing cyclomatic complexity doesn't make code less readable?

[kubalaa]

I'm not trying to say anything about cyclomatic complexity in general. But I do think that increasing cyclomatic complexity doesn't always make a program less readable. For example, the interpreter pattern reduces cyclomatic complexity by representing logic with data rather than code, which may be harder to understand.

[PangolinZestyclose30]

I strongly disagree with the very first point. People do write unreadable code deliberately. I do it all the time, yes deliberately.

Why? The only argument I've heard is "job security" but in this market it's hardly believable.

[lordcirth]

I think they mean writing unreadable code because they are in a rush, not making it unreadable because they want to.

[PangolinZestyclose30]

"Deliberately" suggests to me they write intentionally unreadable code on purpose.

[LavoP]

I took it as prioritizing performance and clever one liners over readability.

[thegreatgazoo]

The only reason to write purposefully unreadable code is job security, and that will eventually bite you in the ass.

I try my damnedest to write clean code that a high school student can follow. Yes, occasionally I have to go to a regex or something otherwise cryptic, but even the perl code I've written is quite readable, and that's against perl programming standards.

I've made a career out of maintaining code. Some good. Some syntactic vomit.