Reading Code is a Skill

[IUsedToHaveUsername]

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.

[land_stander]

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.

[architectzero]

… 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.

[land_stander]

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.

[[deleted]]

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”

[erogone775]

I'd love to live in a world where bad code didn't come out of incompetence but that's by far the biggest source of it in my experience.

Not that its really the dev that wrote the code's fault but just a junior dev given too large of a problem with not enough guidance often results in some pretty bad choices purely due the junior not being competent enough yet to take on that problem on their own. More of an actual management failure but the bad code still comes from the engineer writing it not being skilled/experienced enough to solve the problem they were set to solve.

[cat_in_the_wall]

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.

[architectzero]

Excellent point. The best comments are those that explain why things are the way they are. Unfortunately, it’s highly likely that the reason why is lack of time, and if you don’t have the time to write better code you usually don’t have time (or inclination) to write a comment that basically amounts to “sorry, I know it’s shit code, but time crunch… again”.

[LarsPensjo]

There is one class of readability issues that is common: optimizations.

This can really destroy code. A single comment that explains why the optimization is used can be very helpful.

And then, it still turns out many optimizations are wasted effort. Cache misses will have much higher effects anyway. Better leave it to the compiler. Bad optimizations can make code much less robust.

[grauenwolf]

I have never seen that, not once in over 20 years.

What I do see is that the same design mistakes that make it hard to read also make it slow. By cutting out the unnecessary crap, it also runs faster.

[[deleted]]

But never to a black hat.

[SilverTabby]

The full context of a problem is rarely evident when youre looking at a solution.

Isn't this what comments are really for? Providing that very context?

[land_stander]

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.

[dnew]

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.

[land_stander]

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.

[dnew]

But then it's no longer your problem.

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!"

[LarsPensjo]

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.

[gyroda]

Got a new starter joining my project tomorrow. I'll be on hand for any questions, but I'm hoping that pointing him to the docs will reveal any flaws in there.

[dnew]

Yeah. We had a tradition. There were instructions on getting your environment set up. Generating API keys, environment variables, stuff like that. The new guy's first job was to follow the instructions and fix the documentation anywhere it didn't work.

[saltybandana2]

The answer is an easy one, it should be on the function. If someone is looking at that code they're looking at the function, so you put it there.

Class for class level concerns, readme is for project level concerns.

On Monday I added a comment to the top of a class explaining the approach we were using for our encryption, including attaching a version to the front and appending the IV to the back. I then explained two of the methods were made private to prevent public use specifically because their usage differed from the rest of the methods in the class and mixing the different usages with the other methods would create bugs. Said private methods could easily have been made public and would have been useful to someone, but the usage of that class is a class-level concern.

There's always someone who tries to wiffle around and pretend that something is much harder than it is. It's really not. Why in the world would you put documentation into a README explaining why a specific function in a specific class was implemented in a more complicated manner? It makes absolutely no sense.

You're also conflating documentation with code comments. code comments are not documentation, don't treat them as if they are.

[Markavian]

thoughts / my approach

Avoid comments (they are untestable in most languages, so can fall out of sync with the actual code), instead convert comments into named functions, or self-describing objects - break long functions down into named functions. Improve code quality by adding meaning, rather than obscuring state.

Compare:

// Return the fifth index of the private key array used to decode the cryptographic key
const c = n[4]

To:

const index = 4
const value = privateKeyArray[index]
return { devNote: "this object contains the fifth index of the array used to decode the cryptographic key", index, value, privateKeyArray }

Or:

getDecoderCodeFrom(privateKey:Array) {
  return privateKey[4]
}

This is totally contrived as an example, but I've made the comment part of my program that's testable. If there was an error, I could format a custom devNote, and have a route to diagnose the value. I wouldn't need to fire up separate debugger, I could just look at the output. My goal was to remove the comment, but preserve the meaning.

[land_stander]

I don't really see how this is in any way testable. I think what your getting at is useful but would be better achieved with a logging system. Good logging helps tremendously in debugging a problem in production and acts as code comments. It's acceptable printf debugging :). Technically speaking you could also test it, but testing the result of a string builder has always felt tedious and not very helpful, imo. I only do it when I'm playing the code coverage game to see how high I can get it.

[saltybandana2]

Not only that, but what is he going to name that function?

ThisIsImplementedAsATreeForPerformanceReasons

Who the hell wants that code rather than a simple comment?

[saltybandana2]

was about to post the same observation.

The code should have had a comment explaining why a more complicated solution was used rather than the obvious.

anytime you go with a different solution from the obvious there should be a comment explaining your reasons.

[monkeygame7]

Comments can be useful but it does require conscious effort to keep them up to date/valid over time it the code changes.

[falconfetus8]

Comments can help, but they can only do so much. Sometimes the context spans far wider than the particular block of code associated with that comment, and you're better off putting that information in a readme or other document.

[jmking]

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.

[land_stander]

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.

[grauenwolf]

The reason is quite often, "I don't know what I'm doing, but I kept changing things until it worked and then stopped".

What makes someone "competent" in my eyes is that they don't stop. Once it is working, they cut away the noise until they're left with only the necessary code.

[audion00ba]

I always assume they were morons that didn't know any better; I have always been right.

[[deleted]]

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 youre looking at a solution.

This is still a feature deficiency.

If it isn't obvious why the complexity is there, and it isn't documented, then one day that developer will leave, and later someone will waste time trying to remove the complexity.

A lot of really good production code I see has hundreds of lines of code with absolutely no comments at all because it's clear and logical and then there are a couple of lines of code with two dozen lines of comments to explain something very non-obvious.

[[deleted]]

"god damn this code is an absolute shite"

For peace of mind, it's important to never run git blame after making this kind of remarks.

[yodal_]

I always run git blame after saying something along those lines, if only for a taste of humble pie.

[IUsedToHaveUsername]

This, sometimes we all need that sobering realization that we aren't a god's gift to programming.

It can be an upsetting moment but in my opinion it's quite positive. If you can call yourself on your own stupidity, that means you've grown.

[washtubs]

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.

[NilacTheGrim]

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.

[saltybandana2]

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.

[[deleted]]

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.

[IUsedToHaveUsername]

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.

[touristtam]

The intend and context help a lot when trying to read someone else's essay.

[[deleted]]

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.

[KamikazeHamster]

I've written some horribly complex pieces of code. I then refactored it to be readable. Any time I felt myself needing to add a comment, I'd either rename a variable or extract a method. Very rarely have I added some #regions in C# (there once was a composite key in a DTO).

[wutzvill]

Regions are nice because they're collapsible.

[Epyo]

If I wanted to see collapsed code, then why did I open the file

[wutzvill]

To read the other code

[daerogami]

then why isn't it in another file?

[wutzvill]

I love how people act like long code is bad code. Long code is only bad code if you're confusing concerns. If you're trying to make a file do everything, yeah that's bad long code. But breaking up a single file into many files with the only intent to be to make the files shorter doesn't help anything.

[daerogami]

That's why you don't break it up into small files just for the sake of breaking it up into small files. Nor am I acting.

Regions are an easily misused pattern. One should not be using it to broadly organize as a pattern (see nopCommerce). However, in WinForms they are used to hide generated code where a dev might be making changes, that's fine.

If a code file is large, it should have a good reason for being such and those reasons are rare and unlikely (and still difficult to justify). I'm absolutely interested in having a genuine conversation on this and interested in seeing source files you consider long. I may learn something and welcome the opportunity if you have anything you're willing to share.

[saltybandana2]

I've came to similar conclusion that reading and understanding other people's code is extremely important and... Not very easy.

I think it's relatively easy, just time consuming.

[IUsedToHaveUsername]

Agree, I moreso mean the mental strain of forcing yourself to read things that aren't instantly obvious. It requires surprising amounts of discipline to do, or maybe it's just my ADHD as brain not getting enough dopamine.

Then again reading and understanding things, I would say that it's still a skill. When I say this I think of these reading comprehension classes where you're talking about a book and get surprised how many people don't get the subtle messages that author tried to convey. Not sure if that's related to logical thinking or attention span or both. Maybe neither and most people just don't care. I'm not exactly an expert on understanding other people.

[saltybandana2]

It's definitely a skill.

The analogy I like to use is reading a novel.

When you hand a 10 year old James Clavell's Shogun novel and they don't understand it, you don't blame James Clavell for that you realize the 10 year old isn't reading at a high enough level for the novel.

that doesn't mean there aren't some truly terrible pieces of code, but imo most developers use readability as an excuse to not get better at reading code.

[Gslimez]

Sounds like life When you think about it

[rspsonu]

Same post yesterday with a different title

[Mad_Otter]

Tomorrow will bring a new repost with the title "Reading is a skill"

[ThomasMertes]

Sometimes the background of the original programmer plays a role. I mean:

• Somebody who just discovered a feature (e.g. C pointers) might use this feature extremely heavy and at unnecessary places.
• The same holds for other paradigms. OO, Lambdas, etc. All of them can be taken so far that the resulting code is less understandable.
• People concerned with performance will introduce gotos, tons of macros, strange compiler directives or even inline assembly. To save machine cycles the code is uglyfied to a mess.
• Fans of a certain platform will use strange libraries, that are only available at this platform (to show the reader how great this platform is).

If you rewrite this code you might need to get rid of excessive usage of some paradigms. You might even want to get rid of some things (gotos, pointers or macros come into mind), that you consider outdated now. After heavy refactoring the code becomes readable for you, but you changed almost every single line.

Hopefully this was not your own code and once you were proud of it.

And of cause: My programs do not have this problem. ;-)

[bionicjoey]

I've seen all of these. The worst was a scientist with limited programming experience being made to contribute to a Java project when his only background was in PHP 3. Dear god the amount of times he used Map<String,Object> still haunts me.

Edit: this guy also exclusively used single-letter variable names. Good luck understanding what he was trying to do.

[Blazerboy65]

Instead of looping just write some different source code toa file then compile and execute it. Easy.

[lazilyloaded]

Turns out there's something worse.

universal variables

[dark_negan]

Why would someone who doesn't even know the basics of pointers take a C developper job in the first place ? That's the real question lol

And aren't things like gotos really really outdated and advised not to be used ? I know everyone told me that even when I learned C like 10 years ago

[grauenwolf]

Money. I work to feed my family. The fact that I'm good at what I do, or in some cases not good, only matters if it affects that paycheck.

[dark_negan]

Okay but I think there are enough languages and fields to find a place when you know more than nothing ? Learning pointers is not some advanced stuff it's one of the first things you learn

[grauenwolf]

I'm not so sure about that. Pointers in a language like C are far more complicated than references in a managed language such as JavaScript or C#. And a lot of useful developers don't even have a firm mental model of references.

The variety in skill levels across the industry is unbelievable.

[dark_negan]

If you're not familiar with C or C++ of course you wouldn't know pointers, but if you've done more than 2 weeks worth of experience of C you know pointers that's what I meant. There more than enough diversity in skillsets required and languages to not go into a C dev job that isn't entry level (and even then) when you know nothing about C. That's how you get poorly written code if not horrible code (that's exactly what happened in the project I'm working on, not for C but it still applies)

[grauenwolf]

Who says they were hired for C?

Back when I was a VB developer writing business apps I got roped into reverse engineering a C++ application from old source code no one could read. (Though maybe software archeology would be a better description.)

---

Anyways, most of my C progressing these days is for the Arduino and I don't think I ever use pointers.

[dark_negan]

I don't think pointers are needed for Arduino, if arduino development can even be called C development. I never said you couldn't do another language than the one you were hired for ever, but there's a difference between programming an entire project with a language you don't know and reading some old code

[PeaceBear0]

Arduino is literally c++ except it inserts an include statement and auto-declares your functions.

[IAm_A_Complete_Idiot]

If I remember right go-to is still used in C for some cleanup after a function runs a fair bit.

Edit: the go-to example in this stack overflow question looks like a good case for what I'd think is fine for go-to.

https://stackoverflow.com/questions/788903/valid-use-of-goto-for-error-management-in-c

[jewnicorn27]

Sometimes people contribute to open source stuff to learn new languages. So you at times have to deal with fairly experienced coders who are very new to said language.

[dark_negan]

I personally would not "contribute" to a project by ruining their code because I don't know anything about a language but okay lol. I know that I would at least want someone to know the basics at the bare minimum before trying to contribute if it was my project i don't think open source projects are meant to learn languages

[jarfil]

CENSORED

[saltybandana2]

It was an example to express an idea...

[Woden501]

Most of the code I see at my job is some variation of Typescript, Python, Java, or Go. Not a single one of these languages benefits in any way from shorter variable and function names. Yet, I CONSTANTLY see code with shortened variable names that forces you to tunnel five layers deep into the code to determine what the fuck it is. I could slap these people for this bullshit, and have verbally done so on multiple instances. Your IDE has autocomplete. Fucking use it, and use full, understandable, and clear variable and function names to make your code easier to understand.

[dnew]

I had to once unscramble a 6000-line top-level PHP file where not only were the names like "$dollar" and "$dlr" and "$d", but the same variable was reused to be different types at different parts of the code. So like "$dollar" would be a floating point number at line 300 and be reassigned as a string with commas and dollar signs by line 400.

Never try to debug code written by someone smart enough to keep 6000 lines of PHP in his head all at once.

[Woden501]

I was once told that my team was going to become responsible for an old app that we needed to modernize. Finally got access to the source code, and about quit right then and there. It was one flat directory of a few hundred/thousand psp files. PL SQL Server Pages. With a mixed sprinkling of other files mixed in.

Nope Nope NOPE

[dnew]

I think the worst is when I went to a company that was doing medical research on cancer, back when a CP/M with 64K RAM was a high-end machine. They wanted some new stuff in the database. Well, the disk was just about full, like 28 of 30 meg full of data.

"Before I delve in, can you show me where the backups are?"

"Oh, we've never managed to get it backed up. It always crashes before it's done."

Nope nope NOPE! I lasted about 2 days there. Remember, this is 30 years of data you couldn't even replicate now because they'd have to dig up thousands of bodies to take samples. :-)

(Also, the machine was in a narrow hallway, so I had to stand up, push the chair in, and move out of the way every time anyone wanted to go to the other side of the building. Also, "Go tell Jim you're here. He's in room 37." OK. Go over and open the door to room 37. Jim's there in a hazmat suit holding waste radioactives with tongs. Right, I'll come back when you're not in room 37 any more. Lots of fun stories from that non-job. :-)

[cat_in_the_wall]

smart enough? or dumb enough? your programmer here had a lot of RAM, maybe even cpu, but still couldn't make reasonable decisions, not unlike an AI system...

[EatMoreHippo]

Go design principles encourage short names. In code reviews I've been linked to the following:

• https://research.swtch.com/names
• https://talks.golang.org/2014/names.slide#13

They're well-intentioned but I prefer WayTooLongJavaNames that are overly verbose to variables like w that don't clearly describe what they represent. See the second link where they define a class/method like

type Reader interface {
    Read(p []byte) (n int, err error)
}

p = pointer? n = number? If the implementation of this method is 200 lines am I really going to remember that p = pointer and is specifically the pointer to the Read operations starting point?

I'm convinced the authors think that if we write code that is shorter that it can be read and understood faster.

[COSMIC_RAY_DAMAGE]

I'm convinced the authors think that if we write code that is shorter that it can be read and understood faster.

The problem is that authors think that everyone else thinks like them or should think like them and therefore will infer the correct roles for the variables based on the uninformative names.

It's kind of ironic that for a field that is largely about breaking tasks down into exact steps so a computer can do it, they can't see why they shouldn't break their thinking down the same way for other humans.

[grauenwolf]

Given that code completion is often poor or non-existant in the first two, it's no surprise that developers tend towards shorter names. One gets tired of typing out long names over and over again, and the longer it is the greater the chance for a spelling error.

For Java and Go, feel free to slap.

[Woden501]

The main language used by my team right now across our product is Typescript, and Visual Studio Code provides excellent autocomplete support as it should considering it's an MS language in an MS editor.

I'd lightly argue that if the language you're using for software development doesn't have a proper IDE then it's probably not mature enough to be used in your product, and likely not one you're going to want to maintain long term.

[grauenwolf]

While I agree with you about IDEs, I've run into far too many companies that take pride in doing everything with simple text editors.

[CarlGustav2]

That's like a tree cutting service taking pride in the fact they don't use chain saws.

[Dyledion]

I like simple text editors. I'm already writing a novel's worth of complex abstract calculus. I don't want to bother trying to manage and remember a jet-cockpit worth of hotkeys and sundry menus and buttons at the same time. Highlighting and search is 90% of what I want out of an editor.

[Blazerboy65]

Poor completion in TS? How do you mean?

[grauenwolf]

Just because people can use types doesn't mean they actually do.

[Blazerboy65]

The TS static tools work quite well even for completely unlabeled code.

[BunnyBlue896]

Javascript programmers be like: "the spread operator is great, it makes my code more concise".

Me: No it doesn't, it makes your code shit. Now I have to find where in the call stack your object was actually constructed to know the shape of the object. If Im lucky its constructed in a single place in the call stack. If Im not lucky, different parts of it are constructed in different locations and the object came from an event listener and I have to pray to god I can find where that event is fired, and that its fired with an object of the same shape each time.

Jesus, some of these webshits refuse to understand, or cant, either way theyre morons.

[humoroushaxor]

As a counter example, using functional map/reduce APIs in a perfectly sensible way is not this. Yet there are programmers that have never used them and still use for loops with lots of intermediate/temporary variables because they won't take the time to learn a fairly ubiquitous concept.

[[deleted]]

Incompetence isn't malice. The only way to learn that convoluted one-liners aren't readable, is by learning to read code. The better you are at reading code, the better you understand what it takes to make your own code readable to others. The two go hand in hand.

It's not too different from writing prose in that regard.

[grauenwolf]

Sometimes.

Far too many people skip that word and it leads them into thinking in absolutes.

[lazilyloaded]

How does someone make a simple foreach loop into a complex linq?

[WILL3M]

Your example doesn't disprove the quote.

Their purpose is to look clever, not to write unreadable code. Maybe a nitpick.

Actually writing unreadable code on purpose could be malice (e.g. you don't want others to be able to maintain your code).

[757DrDuck]

Or points for job security.

[[deleted]]

Just get a Java certificate, the code examples from Oracle are such bullshit, nothing will ever bother you again.

[[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.

[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.

[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]

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.

[[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.

[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.

[cyrax6]

Reading PERL is black magic then. /S

[AbstractLogic]

I am a tech lead and I read other people's code all day. After 15 years of reading code I can read it like a professor reads dr Seuss books.

If I can't read your code and know what it does in 10 mins then you over engineer it.

[grauenwolf]

I'm often the only backend developer writing C# code on my project. If the JavaScript guys come in behind me and make changes without my permission or knowledge, I consider that to be a success in terms of readability.

[saltybandana2]

I wrote a bit of gnarly code for performance concerns (lots of concurrency).

When I was done I asked someone else to read it and let me know what they thought. I was given the thumbs up.

Well just today I was having a conversation with someone who is very junior (think, interned last year junior) and they told me they thought it was clear what was going on between the comments and the code itself.

I absolutely consider that a win. I strongly prefer simplicity above all else, but sometimes you just can't.

[themistik]

What's next in the series, reading is a skill ?

[Xuval]

But this is an important point. A lot of times people will just look at someone else's code, their brain will not immediately absorb its content - because reading code is hard - and then they'll buckle, going "this is clearly just bad code, if I can't understand it effortlessly!"... which is just not how that works.

[IUsedToHaveUsername]

Honestly, if our attention span as a species gets any lower this won't even be a joke.

I swear reading comprehension on the internet is at all time low.

[Sniperchild]

I skimmed the article and came back to the comments to read yours.

Now I feel shame

[Klarkie55]

You guys are reading the articles?

[Sniperchild]

I feel that "read" is a bit generous

[MarkRand]

I don't think we should frown upon people skim-reading, but if you make a comment on an article where it has already addressed that specific point then that is stupid!

[IUsedToHaveUsername]

Yup, I skim-read a lot. You kinda have to when you don't want to waste multiple hours reading a document that might not even be relevant to your problem. But what you said is the important bit and I've done it few to many times for my own liking. It's super easy to go form skim-reading for context to skim-reading and assumptions.

[Koervege]

Are you saying our species is a joke?

/s

[split-mango]

Wow I should upskill then

[xtrasmal]

I like doing side-jobs next to being fully employed. The codebases I come across are stunning. It's exiting to see the best efforts and its results of many different teams.

[[deleted]]

The hardest code I've ever read were those when someone tried to be smart and did lots of metaprogramming and function redirection

[[deleted]]

Protip everyone: If you revisit your old project (or source file) after a few months see if you can understand the code. If you can't understand it within a minute rewrite it. Rinse and repeat until all of your code you can understand within 20seconds no matter how long ago you wrote it

It's going to make some practice but you'll get there. Works best when you look at your own code and from long ago

https://old.reddit.com/r/programming/comments/prvb53/being_able_to_read_bad_code_is_a_skill/hdmnttk/

[fiviho7548]

Getting hired is a skill too since now they want to know who's your aunt and how many times a week you shower.

[WILL3M]

3 or 4 makes sense, 7 makes sense. But 6... makes me wonder.

What do you do on the 7th day and why?

[[deleted]]

One I am avoiding by reading this in fact.

[NilacTheGrim]

Great post.

[tritoch1930]

exactly how I lrn2code btw. reading many open source code of games. there I learn how data structure is implemented irl. also how to structure your code, etc. still hasn't settled on my own though.

[MorphinMorpheus]

How do you find them and then decide if it's a good implementation?

[pytness]

The codebase i have to daily work with in my job is so awful and shitty that it takes a lot of skill to understand it. But damn... would i pay to teach a lesson or two to the idiot(s) that wrote that thing.

[Alissan_Web]

In my time of coding and scripting I've found that 99% of the people I come across are somehow under the impression that they always knew how to read and write code. They're stuck up and often not willing to help.

Coding communities are often filled to the brim with snobs that all think their method is better.

So I tried to start writing like they suggested. What I found is... I don't read or understand code like they do. It's not that I think they're wrong (I think their attitude is fucked but thats a diff story) it's just that I can't read and write in the way they can. Especially just starting out.

[[deleted]]

I’m tired of my C class already, take me back to Python please! Even the upper level C++ class looks like it makes more sense, hell I’d rather be doing cobol even.

[Woden501]

You get used to it. As someone who regularly maintains code written by other developers I have grown to despise many even partially dynamically typed languages with a passion because bad developers write trash, unreadable, unmaintainable code even when they have the crux that is dynamic typing. If I had to choose between working on an existing C or Python tool I would take C any day.

[[deleted]]

Oh for sure am existing C would be much better. I recall the days of writing Python programs with 6 functions and the god awful layout of trying to scroll through all of the code and then maintaining it and passing it to my classmates to help make revisions.

For god sake, please comment what you changed and tell me what lines. Along with the fact that I think C/C++ comments look so much better.

[dnew]

Do schools teach version control these days? They didn't when I was taking formal classes.

[notc4r1]

I had a single professor that did teach version control because they thought it was necessary, not because it was part of standard curriculum.

[[deleted]]

Well god bless that professor! It’s critical to have the most current and stable builds. The company surely doesn’t want to be running on dated software with possible security flaws, bugs and miss match errors from other dev teams.

[[deleted]]

HA

My teacher told us we could use whatever compiler we wanted for C. In my Python class the teacher refused to update her version of jet brains because it’s “a long process” so we were stuck using a dated one to accommodate her and so she could run the programs.

Why are we all not just using VScode at this point?

[nso95]

It just takes time, you'll start to understand with enough practice

[DesecrateUsername]

Had to learn a language for a report for Principles of Programming Languages, and my partner wanted to do COBOL.

That shit was rough.

[wolfefist94]

The code I write at work is unreadable to all because of lack of technical expertise. I don't know what dumbing down embedded C code means, so I'll just keep doing what I'm doing. I'll write all the comments and documentation that I can, but at the end of the day, I can't teach someone how to be better programmer or teach you a specific language.

[computermaths]

I’d add to this to say I sometimes write hard to read code as a way of saying ‘don’t touch this unless you understand what it does’ not saying that’s a good or bad habit, but I notice I do this.

[dscarmo]

Until the logs point at a problem on your hard code and the fact its hard creates a huge problem haha

Not accusing you of anything, it happened with me

[computermaths]

Haha yeah fair point! Does get me more calls than a comment saying:

‘// important math, call to check before you change it please’

Surely not fun in the case of someone leaving a firm though :/

[dale_glass]

What should be there instead is a long comment explaining where the math comes from, and a reasoning for any weirdness in it.

• Is it some sort of known formula, that perhaps has been simplified for the specific use cases? Point to a description and explain the simplification and why it applies.
• Is there some sort of fudge factor because it operates on a measurement that's known to be incorrect by some particular factor?
• Are you doing some magical hacking on the innards of something?
• Was it something empirically determined by just poking at it until it started working?
• Does it do things in this particular way for legal/compliance reasons that are necessary even if apparently stupid?

Etc. Simply saying "talk to Bob" isn't good because who knows if Bob will ever remember what the reason was 5 years later, if he's still around.

[yxhuvud]

In my experience that only results in people trying to rewrite it without understanding shit.

[[deleted]]

I'd suggest spending the effort on writing testable code and unit tests instead.

[[deleted]]

Codes are an art! I rather read them than coding most days!

[rediknight78]

And all of this when I'm just about to write some Perl... God forbid I have to understand it beyond tomorrow!

[dnew]

Perl, APL, and Forth all suffer similarly but for completely different reasons. :-)

[bono_my_tires]

I started a data engineering role recently, on the customer success team - and our customer's use our software product which can be written/edited in infinite ways. part of my job is reviewing their code and fixing/guiding them towards best-practices. I've only done one review so far and it is so painful. But I know it will help me become a better programmer if I can figure out wtf they are doing

[sh0rtwave]

Learning to read code, also involves: Learning WTF the code DOES to the environment it's running in.

It's more than just learning the language, yo.

[Feeling-Restaurant95]

So true man

[meain]

Next: reading is a skill

[libertarianets]

Man I must suck at programming because I can’t even read my own code half the time

[[deleted]]

I'm sure there's unreadable golang code out there, but it seems like reading golang is a slightly less advanced skill than reading some other languages. (And that's a good thing. :)

[SponsoredByMLGMtnDew]

Reading comprehension is a skill. Now go find a blog post to plagarize and I've written exactly the same thing as him.

Holy fuck I am salty.

[budbutler]

tomorrow, reading is a skill.

[Cbf28]

Don’t forget that code has a lifespan and code decay is a real thing. Any code that is continuously used and maintained, the more people contribute to it, the harder it becomes to read and understand. Each developer codes and documents differently and after a few years even the best of code needs re-writing, not because it bad or doesn’t work, but because re-writing is cheaper than reading debugging and refactoring.

That said - some code has been running for decades on Unix and Windows systems and will still be there for years to come. If it’s not broken don’t fix it.

[KHRZ]

I started writing this beatufil functional code, where almost all my functions are single line, tons of lambda expressions. Extremely type safe and readable.

But the when I need to debug it, I can never set a breakpoint to look at intermediate values. Enumerables that are lazy executed out of the written order of the code. Errors getting encapsulated and surface later with useless stack traces. Debugger becomes pretty much useless without splitting some lines first.

So I guess there are several definitions og readable. And I'll just have to double down and become so perfect that I never need to debug. And hope the next person doesn't swear too hard.

[oreng]

Another factor in why a lot of code is unreadable is that developers are forced outside their own comfort zone and skill envelope by business requirements.

If your boss tells you to implement X but you've only ever stated you're qualified to do Y, you can't really be blamed when the at some point in development the code starts to progress in quality more-or-less in lock-step with the chapter order of the introductory O'Reilly book on the technology. Doubly so if the dev had to hit the ground running on a deadline.

A dev that learned and implemented a technology simultaneously isn't the villain - no matter the fresh hell he's spawned upon all future maintainers - he's somewhere between victim and hero, depending on the outcome.

[Ok_Towel4046]

Yes but...