I think Prime hasn't seen enough terrible code bases to understand what an unreadable codebase looks like. Yes readability is subjective but if you have 20 lines of nested if conditions cause you didn't know refactoring was a thing and 20 lines of repeated code (but each line slightly different) cause you don't know how to use for loop then I would say most sane ppl would say that's pretty unreadable.
He is a lucky guy. If readability doesn't exist or just in the eye of the beholder, then why are we keep linting, styling, syntax highlighting, structuring, designing the code? Nothing matters if it works, right? I do accept that it is highly subjective and it is based on context, but that's why languages has their own styles that people follow and judge code on. Yes, it also depends on what the business requirement is, for example I think the Linux kernel code is highly readable, well designed for what it has to do. But from a simple webapplication we can expect even higher standards of readability, since its code is not as critical and better aesthetics are easier to achieve.
That's what it looks like. To me, a terrible code base that has some wild side effects like a code base that uses both Angular and jquery to modify the DOM and on top of that use "any" for all type annotations
Exactly! I think Prime and most of the comments here haven't read *actual* bad code. Not complex code that solves complex problems, not code in languages/frameworks you're not familiar with. Just simply bad code. Im talking about simple python scripts written in a way that look like assembly, global variables that are used loosely, functions inside of functions inside of functions that each of them are called just once, bad names for everything, functions that alter global variables with no warning or documentation whatsoever, repeated code in multiple places that could've been easily extracted into a function, endless nesting, condition's being checked multiple times for no reason... Basically the opposite of what any sane codebase would do, usually for lack of experience, or an abundance of doing things on your own way (aka Tom is a Genius syndrome) Sometime "bad code" doesn't mean ugly code, or complex code, or poorly optimized code, it simply means plain bad code.
While I am not entirely sure prime has seen truly stinky code, I agree with your take. I think there are certain code practices that we can (mostly) agree decreases readability of the code to whoever is reading it, one example is code with high cyclomatic complexity
I have seen those codebases and the answer as a maintainer is: - Put a test there - Eat the elephant one bite at a time. With enought sweat tears and weird slightly erotic dreams that you wake up from scared about what you have discovered about yourself... You can get it down to 18 lines of nested ifs. And that's a lot better. The first nested ifs are often the hardest to fix.
Sometimes when I look at my own code I go "why the hell did I do it that way". Then when I try to fix it I go "oh, I see" and regret that I'm still unable to do it any better.
A company is still using a piece of code I did 3 years ago, when I went back and saw it was still used a lot and I could still read it, I felt really proud of myself ngl even though it was most likely an accidental W.
For me writing readable code means to not use complicated patterns, syntax or control flow until it’s needed. Yes code for complex issues will be hard to read, but most times that’s only a small part of the Application. The rest can and should be simple!
Generally good. Also helps the compiler do the good crazy stuff for you. With complex language features you usually add code for all the complexity the feature should handle.
When it comes to code i try to live by the mantra - "As simple as possible, but no simpler". Pretty much just another way of saying the same thing as you
Yes, readability is subjective, but that doesn't mean it's not a real thing to achieve. In general, one should try to write code with an eye to someone else having to come in and add features or fix bugs. Even if your code is perfectly flawless, you want it to be OBVIOUS that it's flawless so that the reader can continue on to the next section of code on the suspect list. This is a different discussion than "reading other languages is difficult" or "understanding an entire interconnected system of code is difficult". You're taking these very different topics and calling it "readability". And yes, sometimes, the issue is that the individual coder trying to read the code isn't that bright, or too new. This is why most code bases have "new, simple features" coded by cheaper mid-level coders, while the senior coders are tasked with solving the problems that those less-skilled coders created. The less skilled coders don't have the skill to parse out such problems, yet. But this isn't a "readability" issue, nor is it a subjectivity issue. It's just a skills issue, which doesn't preclude readability as being a reasonable goal, especially for senior coders. In particular, senior coders should focus on keeping things simple and readable so that the newer coders can be tasked with fixes and upgrades, so the senior coders can focus on more advanced work.
What about poorly designed systems? Not a skill issue when you fighting the code base all the time and piling on more technical debt with each iteration as a ripple effect. Not a skill issue when you waste time trying to make sense of the code because previous devs used arcane naming conventions, patterns and did not follow standards. imo
Sometimes the system is poorly designed. And sometimes it's a skill issue between the reader g and the code. If you're not familiar with concurrency and multi-threaded programming, you're going to have a bad time debugging race conditions. Just because concurrency is hard to get right doesn't mean it's wrong to use it, and the code should be rewritten for some junior to understand in a linear fashion.
@@edwardcullen1739 the point is that to write code such I can come back and be able to understand what the heck is going on without having to spend a week picking up esoteric skillset to do that. But some "smart" folks think that esoteric skills is what makes them good as opposed to ability to express complex ideas in simple enough manner that doesn't need esoteric upskilling to participate.
This is like saying that what words I use in my sentences doesnt matter, you can use any words and any words can be as descriptive as any other words, because language is subjective. you cant can't simply ignore the importance of word choice and sentence structure. Language can be subjective but there are shared conventions and meanings that allow me to convey my thoughts more clearly.
I assume that you are talking about readability, but not sure what is the point of your analogy. 'word choice' is about semantics, while 'structure of sentences' is about syntax. The same way a compiler can't understand a program with syntax/type errors, you can't understand poorly worded/structured sentences. Those things are not about readability, but about understanding, about the meaning. In your analogy, readability would be the type of font that you use, font size, formatting, text color, etc, which you would probably agree are highly subjective and do not affect the meaning of the sentences. Readability is about being able to parse code, not understand it. And that's why it's mostly up to your preference.
@@clawsie5543lmao, no. The structure of a sentence directly affects readability. Eeeeexexamplö for I mean ye somewhat may that little be harder to well read but under… standable? This sentence is a mess that is hard to read but you can understand it after some thinking. Bad code is the same
And yet they suffer the "good programmer syndrome": They genuinely don't understand that their code still needs to be able to be understood (and modified without breaking something undetectable) 10 years from now, by people who were not there when the system was designed and barely understand how it works.
The missing aspect of readability is understanding the data that code may be operating on. Without this context, I can really struggle to understand what the code is doing.
@@sk-sm9sh I think what he means is, you need to understand the domain itself, how data is related to each other. Not the data types, etc, thats still code.
@@sk-sm9sh ah, i understand what you mean, you are talking about weakly typed languages, correct? in that case, i concur, thats why i strongly prefer to work with strongly typed languages. but to find out how data is related is very easy, you ask any person that works/worked on the project to explain what its supposed to do. aka, the context Joe(opening post) is talking about. understanding what the program should do (context), and figuring out how the program works (code), are sometimes not aligned. when you know both, you can figure out a way to go forward.
Ever dived into code with #ifdefs nested every 5 lines? Or stumbled upon files where every line is sprinkled with 10+ magic values and intricate bit manipulations? While coding styles vary, there's no denying: readability isn't always subjective.
Agree. Well, someone might come along here and say that there are people who can read this kind of code quite well actually. But even if someone has the experience and skills to read such code, it doesn't mean that the code itself has become more readable. It's just that "you" who have learnt how to read poorly written piece of mess instead of code.
@@tokiomutex4148 I mean magic numbers are objectively bad since you have to know what they represent to understand the code. If it's a constant with a decent name at least you have something to go on.
is there way to structure your functions so that they are easier to understand? Yes. Is there way of naming variables and functions so that they are less confusing? Yes. Is there a way to structure your codebase so that its easier to understand? Yes. See? You can make your code more maintainable even if your problem is difficult.
Easier to understand to who though? I work on a smallish team, and we have a micro services based codebase that spans everything from low-level embedded and signal processing code in C/C++ to standard backend web-server business logic code, to web UIs, and I think what is "readable" is very very different in each area. If you are doing something that leans heavily on maths or comp sci theory, you might have lots of functions with mostly one-letter variable names, because that is the most readable way of writing that function IF you have the background in theory to understand it, because all the textbooks and papers will be using those same letter names for the same things. And you can probably assume that if someone isn't familiar with the underlying theory they shouldn't be editing that code. Conversely though using lots of one-letter variable names for anything that isn't a simple loop counter is a code-smell in most other code. But always you will run into the problem where people who could read the code if the variable name was "radius" not "r" then find it difficult to read when they need to read it for context. How do you balance those things? If I have to split one common mathematic expression over 5 lines of code because I have huge expressive variable names that spell everything out it becomes less concise and harder to verify by inspection, sometimes. Likewise for people who spend all day writing C-style code, they are very used to seeing and writing raw loops, in a way that is highly discouraged in modern C++/Rust where iterator/algorithm statements are considered far more idiomatic. But which group of people is going to read your code? And if it is both groups, for code on the boundary, whose is "more readable" Readability always depends on the domain, and the language, and the person reading it. There are maybe a small subset of rules where we could probably find everyone agrees (nested if statements are bad, so on), but it's not a huge list, and lots of them have qualifiers. Almost everyone agrees small functions are better, but how small? 50 lines? 30? 5? Maybe the function should "do one thing", but what you consider to be "one thing" can vary. I write lots of Rust, and I have a colleague who writes lots of C#, and both can be used for simple web-server code quite efficiently. He reads my rust and finds all the odd symbols and the requirement to mentally keep a bit of a tab on where ownership is flowing and what the code will boil down to onerous and thinks it is difficult to read. I then read a similar web-service he has written in C#, and stumble around reading 600 lines about IThingies created by IThingyFactories sending IMessages to AbstractWhatsits and get annoyed because I can't find the 20 lines of code that actually do the work. But other people on the team who have systems-level code backgrounds find my code easy to read because lifetimes aren't really that hard (most of the time) and its natural for them to think about what code boils down to, and others who have OOP backgrounds find it really easy to digest the top level class hierarchies and enjoy feeling productive as they do all the busywork of unit-testing all their boilerplate. I don't think you can really objectively say either one is "more readable", one is more readable to me, one is more readable to him. I think if you are working a particular sort of problem, and your code will be read by people with similar backgrounds, experience and skills as yourself, and you are all working together for some time and have built up the same library of idioms and patterns, it is quite possible to define what is and what is not readable. But how often does that happen in any code base that is non-trivial?
If you're progressing as a developer, then the "what idiot wrote this?! Oh, me." moments are unavoidable. You're going to be learning things you didn't know before, which will change what you use and when you decide to use it. I'd honestly be more worried if I look at a lot of my old code and think "yep, absolutely perfect, this person is a genius."
I have gotten to the point where it's more like... "Oh, that wasn't nearly as dumb as I feared it was going to be" and I'm not sure if that's a good sign or not.
I think it can be broken down into a few stages. - You see no problems in your old code, because even though you had no idea what you were doing then, you still have no idea what you're doing now. - You see nothing but problems in your old code, because it was complete garbage and you're now skilled enough to not write complete garbage. - You see nothing but problems in your old code, because even though it wasn't garbage, you're now skilled enough to make a lot of improvements. - You see nothing but problems in your old code, because even though it's completely fine, you've changed your coding style and no longer find it aesthetically pleasing.
I disagree. You should maybe do this early in your career. But if you constantly think code you wrote 3, 6, 12 months ago is bad, that means you're likely still writing bad code - because in all likelihood you're calling code bad if its just unfamiliar and not in your current preferred style. You're not improving, you're running in circles.
This is the same philosophical domain as "I apologize for the length of this letter. I didn't have time to write a shorter one." To me, clean code is about not adding incidental complexity and making the inherent complexity of the problem being solved as obvious as possible. It's certainly subjective where you stop of that scale right now, but many objective scales have been developed, e.g. big O.
One of the most valuable resources in YT on my learning path. Still watch all of his videos, mostly on the second monitor. He's excellent at explaining all the concepts and keeps it real without smashing in thousands of frameworks etc.
@@QckSGaming Agreed. Something I always hated about tutorials that were supposed to teach you a specific concept was how many times they resorted to just slap library functions on a few lines of application code
Usually, the person writing the code will be better than the person who will have to maintain the code. True skill is the ability to take complex ideas and express them as simply as possible. A mid-tier fresh graduate should be able to read and comprend your code. The issue is when you have "god tier" devs who write code that's beyond all human comprehension. It's part of the idea that developer responsibility extends beyond "I checked it in and it passed the compile check".
Increasing readability of a language, leads to --english-- I mean COBOL Increasing maintainability leads to a language with builtin documentation, so lisp I love Lisp, so im probably biased
I love apl and lisp and even if they appear impenetrable they make complete sense to someone that just took the time to understand the language. People have very shallow views about what readability/maintainability is or should be
Both can be objectively measured. Readability Is a ratio between "need to know first" and "now can read the rest". You can think of it as a time to onboard a new programmer compared to lines of code in the app. Maintainability is similar, because it's again about how much you need to know and how many lines you need to touch to add a feature, or fix a bug. If your average junior can navigate your codebase after a short onboarding... it's readable. If he can work with it effectively, it's also maintainable.
If such things could be predefined for objective measurement programmers wouldn't have a job. Neither code readability or maintainability of code can be objectively measured, only subjectively interpreted. Readability is always subjective since the text in each part of it's own ratio cannot be predefined for evaluation in a test only evaluated as someone re-reads it later. Maintainability is only measurable AFTER it's been maintained but it cannot be evaluated because there is nothing to compare it to was we don't have access multiple universes.
@@TheNewton Readability is subjective for YOU, since it's based on YOUR knowledge. You can read English books, but you cannot read French ones for example. They are different for you, even though their readability is basically same. The same applies for say Russian books, because they simply have a different character set. Again, something that you need to know, or learn, but Cyrillic isn't harder than Latin. Then, there are Japanese books, which are objectively harder, because they have symbols for words, so to read (not even translate) their texts, you need to learn those thousands of symbols. To learn their language in general, you'll need to learn both the word and it's visual representation. So, we've established a very tangible difference between some languages and Japanese. Reading Japanese is OBJECTIVELY harder. The same applies to languages themselves (how many rules you need to use to build up a sentence, for example). The same applies to every book (how obscure words and how obscure sentence rules are used in the text) Etc. Therefore, even the readability of a source code is measurable. There is no practical difference. It either uses the "minimal and typical" set of features to do the thing, or it uses obscure constructs for it. (what is typical and what is obscure can be statistically analyzed through scanning of a github, for exmaple). It is either consistent with naming, with project hierarchy, etc. (so that you can learn it on one part and apply it on another), or it is not. Again, measurable. Etc, Etc. And for what it's worth, there are a plethora of valid reasons why make something less readable. But it's still less readable.
@@jamesm4957 Yes, they tend to be readable indeed. I didn't say, nor imply that a large codebase must be readable by junior. It might be unreadable for many reasons (long running project with several generations of code in it, performance reasons, hacks, different teams with different philosophies, etc). That being said, It still ends up being harder to read and we can almost quantify it.
I think we're moving from one extreme to another with this video. Yes, the "maintainability and readability" is not a code author's responsibility only* and yes - the experience of the programmer that will need to read/contribute/maintain it also matters But we can't also just say, that I will write whatever I want and however I want ... and put all of the responsibility to understand the code to new programmer all by himself It's like Tsoding said - it's a double-edge sword. Author is responsible for creating most straight-forward code possible (since there are always a trade-offs, so sometimes code will not always be straight-forward... especially for some serious/complicated stuff) and help new contributor to understand it. New contributor on the other hand is responsible to adapt to it, despite his preferences. If he doesn't like the style or a way in which this code was written, he will fit better somewhere else. Somewhere where code meets his preferences and he will feel more comfortable and the learning curve will not be too high to overwhelm him
"The maintainability and readability is not a code author's responsibility" is literally a justification for "I will write whatever I want and however I want ... and put all of the responsibility to understand the code to new programmer". It absolutely is the author's responsibility.
Well not necessarily true what you say. You can try to write code that is easier to read than to write, if you embark on this task then it alone makes it pretty damn hard to write any code :)
Unmaintainable code is real. It's out there. And it will find you. And when it does, then you'll regret telling people that it's not their responsibility to think about readability when they write code.
This is a very poor mindset to have, "The maintainability of the code also greatly depends on the ability of the person to maintain." is just giving him an excuse to write crap code then say other people have skill issues. A skilled programmer can simplify problems. Sure if you have a high complex problem, it will be harder to understand but it shouldnt be hard to read. Its a massive problem when a dev has a very simple problem and thinks he is smart and builds the most complex solution in the world.
Readability is basically a measurement of someone's ability to keep their code simple. Your code is poorly readable if I can take it and do it in fewer lines with less indents, fewer function calls, with similar lines grouped together, and better named variables. The take that readability is a skill issue is true but only for the person who wrote it not the person reading it. Your code should be as self explanatory as possible with comments explaining where it is not.
I was about to post a long description of the nightmare app I took over at my new job to get some advice or validation or something ... but it's description wasn't even maintainable. I'll just add that a big part of 'maintainability' can have a lot to do with overall architecture, especially when you're a team of only 1.
What do you mean "readability doesn't matter"? That's like saying it doesn't matter that books be readable. In fact, I often write code as though I'm writing a children's book. If I showed my parents this code, could they grok it? Your code should be written so the steps of the algorithm are clear, and there should be established rules that must be followed (if they can be enforced via linter, great) to ease readability and maintainability.
i may be in a ts and js space, but the comment of "go pull up any github project and read it, its gonna look bad" i completely can not agree with this. I have spent dozens of hours reading people's code on github and there is a clear difference in how easy it is to understand the architecture of the program. Some people know how to write code that is easier to work with. we can not deny that, and in itself this is a skill.
Readability can be proved through A/B testing. Implement function in 2 styles, get a survey on random engineers, and measure how fast they can figure out the right answer. And unless result is 50/50 in which case it just means doesn't matter and best way to solve is to toss a coin if however outcome is 20/80 there is clear benefit to one style over another. We just didn't figure out to do that for some reason yet. Instead we typically make decisions based on opinion of someone who's going to stick through flame war the longest and who uses the most inventive rethorics basically somewhat same way how we politicians develop laws. Which is not always the best thing for majority.
I disagree with this when working in a team level, if the code is not readable is hard for others to maintain. I had see TS codebases full of any's and without documentation, if is a skill issue to maintain that, I don't think I will reach that level. Complex code can be readable, but other code is not readable because someone do not care about it.
Most people watching this won't realise that prime is in a very rare position in the industry, being able to choose how he formats his code. Most programmers who work in teams for companies (that aren't startups) will already have established practices for coding conventions, linters and senior Devs to check that the code follows them. That prime didn't mention any of these once means he definitely didn't go through the route that most of us will take.
Yeah, I have only been coding professionally for a few months, but the best projects were definitely ones where even just onboarding didn't require me to get used to seven different people's preferences and coding styles
@@TomNook. Yeah, I've never been able to use my preferred style (which is objectively better, obviously 😉) because someone else has already defined a style I need to adhere to.
@@edwardcullen1739I had see projects with different styles but they had linters, rules and good PR reviews you need to follow. So no matter your style, if you follow that the code will be maintainable not matter your style, that's the way to go
Programmers need to read some philosophy of language like Wittgenstein. This question is answered by Wittgensteins concept of language games and communities of knowledge. Also, there is a third perspective, its just subjectivity and objectivity - there is inter-subjectivity and thats what these discussions by programmers always miss. Conventions exist.
😬Sorry bro but you're wrong about this (with all due respect!). If the code is not maintainable and readable, it's not reliable or suitable for anything "mission-critical." It's more difficult to understand & fix bugs, and it takes much longer to implement new features. You have a bit of a not-customer-facing perspective. Someone has to explain insecure communication protocols, weird UI choices, inconsistent & unpredictable behaviors, system failures, data-corruption & data-loss, patch-application procedures, painful upgrade paths, lack of requested feature support, lack of device support, etc. to partners, distrubutors, OEMs and end-users.
There's some simple things people can do to improve code readability (and therefore maintainability) that they don't do - like give variables appropriate names, have consistent whitespace etc, basically stuff that is entirely cosmetic in the code. That stuff is important to get right and has no downside. I think sometimes people end up being told that readability is about making sure a junior dev can read their code though, and in some applications that's okay, but sometimes you end up with people using slower/less space efficient implementations of things just to make the code more simple to understand, and in those scenarios you have to think about whether it's worth it. Like when you take the famous Quake inverse square route function - that code isn't 'readable' at all, but it did the job it needed to do perfectly.
TBH. I'm NOT 100% onboard. With so many things in software it's often a question about the average skill level of the team, not a single dev. Codebases using a bunch of service patterns and God forbid an AbstractFactoryFactory is perfectly readable for a team of seniors. A team of juniors would probably just give up. If You're the only senior in a team of juniors it's your responsibility to write the code in a manner that your TEAM can support this. So it has to be readable and maintainable for them. The definition of readable and maintainable depends on the team setup. Same goes for complexity
Readability to me is using correct indentation, not using weird abbreviations for names, not trying to be crafty with pushing as much stuff as possible in a single line and adding the comment here and there to communicate the intention. Add to that that functions should be kept down to a reasonable length and not be nested too deep. I'd put it in a single line as: don't be a show-off.
I modified the code of Dmenu by hand and it changed me. Dmenu is designed to be good for it's scale, exclusively. Globals, few files and functions... Also, it's designed to work well in the context of low level C. I didn't get that and started refactoring it, and then it occured to me. If you want to scale it, then take odeas from it and start from scratch. I had never thought this way before! I thought code is this balloon that you stretch to it's limits and deflate into a maze like heavy mess as you're going up and down in scale with it. Nowdays I write code that's readable by the person who understands code written for the current scale of the project. Maybe that's bad, but wow, this is a way more complicated notion of readability. Thank you Dmenu!
If you need an explanation of 10:00, look no further than 12:40. Basically, "There is no direct and simple prescription (linearity) for everyone to understand. Instead, there are a lot of interconnected ways to look at a big project, and the approach will vary person-to-person. So there should be considerations that make sure no matter what ways (multi-dimensionalness) a person analyzes the codebase, whatever insights they get should reinforce each other (diverse entrypoints) to build understanding - even if it's done in the readers' own chaotic and unique way, even if they have imperfect information (lossyness) on the theories involved."
5:00 I think that is exactly what maintable code is. You do not have to know or understand the entire Code base. But you know exactly what Kind of Inputs should lead to which Kind of outputs, so you can still fix and improve it. But this also requires readability, in the sense that the code is documented well enough (or self documenting) that you actually know the exact Inputs and Outputs, what Kind of errors may occur and these might be handled.
There are several factors to readability and maintainability. Try reading minified or obfuscated code and see if that is maintainable :). Compare e.g. the original Obfuscated Tiny C Compiler with the initial unobfuscated version checked into the Tiny Compiler repository. Using sensibly named variables and a consistent formatting help a lot in readability, especially coming back to code after a while. Being unfamiliar with programming languages, libraries, programming styles, etc. make code harder to read, but as stated those can be solved by learning those. Adding comments to explain an algorithm, or link to external descriptions of those, can also help. Especially when you have things like the complex nested for loop matrix multiplication optimization. Having something like "process the next 2x2 submatrix" and "invert traversal of matrix B to align with cached reads" will go a long way to help understanding that code later down the line when you have forgotten the specifics, or someone else is looking at the code wondering what the hell it is doing. It doesn't need to be a PhD thesis, just enough to give the reader context on what is happening if that is unclear from the code.
Good code is like literature. For the first 100 pages of Dune you don't know wtf is happening, but that is because it is *good* and doing complex things with great skill.
Is it subjective? sure. Can some subjective things be better than other subjective things? absolutely. Why not name functions in Chinese (oh you can't read it? skill issue.)? why use linters and code formatters? why not just put all the files in the root directory (or better yet, just put them in a single file)? I don't think it's a good take, Prime.
Yeeted at 2 min. The reality is, in any kind of collaborative environment, you are going to have programmers of all different skill levels looking at a given chunk of code. Choosing to optimize the way you write code for accessibility, favoring common paradigms that other engineers are likely to be familiar with, establishing standard implementation patterns throughout your codebase -- these are all worthwhile efforts with good ROI.
There's complex code and just bad code. Most people think bad code is un-readable and un-maintainable. Complex code _when that complexity is necessary_ is generally fine
I started working on a project which codebase is impossible to follow. The original developers left the project and nobody in the team fully understands how the project builds and deploys. It is just beautiful.
When I have a task that can be implemented as a long chain of maps and filters, I usually break it up and have intermediate fully typed variables so that I'm not only trying to limit the size of the mental stack required, but also allow the type inference to not break for the entire chain when I'm working with it. I try to limit my complexity budget where I can and so if I do something clever I try to make that the only clever thing in that bit of code. This helps me avoid writing code that I'm smart enough to write but not smart enough to understand when reading later.
If readability doesn't matter why don't we optimize code for compiler speed? Shortest variable names possible and minimize whitespace (no new lines or tabs). Just put all your code in a single line of a single file. Obviously, there are good reasons to sacrifice readability. Sometimes complex problems need complex code. However, just saying that anyone can write in whatever style they want and telling everyone with a problem with that "skill issue", is absurd.
I like to write one line if statements. Like this if (some_int > 5) return some_int if (some_int 5 => some_int case x: int if some_int something_else } That was okay, because it wasn't an if statement, it is a match statement and that's how you just write match statements in Scala. And therefore this is readable, but one line if statements are not...
In the code I write, especially in the newer ones, I always try to add an explanation to introduce the next person to the mental model I thought when I wrote that code. By doing that way, my code might not be very very well documented (sometimes I forgot a few things or add some whys, or even to end a phrase) but I want to allow them to get into my mind. Of course, to keep the code readable, I also adopt other precautions.
Industry standards for personal code and industry + maintainer standards for team code. Years later you’ll still be able to quickly understand/ modify it even if you moved on to another language Lots of ‘geniuses’ who’s code, no matter how simple, are an enigma simply because they can’t be bothered.
Tsoding shows that persistence is key. I used to stream coding on twitch too, I even had more viewers than him at one point. He kept going for a long time before his numbers started to raise
Maintainable and readable code is easy if you put the work into it.if you know your code works and you've covered your code with tests you can make it more readable by renaming variables properly, extracting parts of the code to methods or classes. Write, test, refractor. You can have the greatest story for a book but when your sentence structure is so illegible so that others can understand it you're not a good author. Practicing a profession means adhering to common standards and making your work as understandable for others.
Readability is a real thing when you have some hotshot developer that wants to write everything as code golf and develop his own unique syntax for traversing arrays, or special snowflakes that want to make their interface different from 30 other ones that are all identical. But how hard their code is to read is not really the issue, but rather their inability to work in a team like a normal fucking human being.
It's why I never get annoyed at too many comments (If it becomes obnoxious they can easily be remove), but get eternally frustrated by the hubris of some programmers to never leave a single comment. I understand that it might offend some people's sensibilities to have their code base littered with comments, but I think it's even worst when working in a team of developers on a project to expect to understand some horrible deeply nested if statements (That might be necessary). I've been told I comment too much sometimes, but the amount of time people have appreciated the facts I leave comments in comparison to parsing "Tom's" code uncommented code is staggering.
Regarding the thing about spending the time to learn what's going on, that's kind of what I did with an OSS program that was broken when making some syscall on NetBSD (It was some component of i3 window mgr I think). But it definitely helped that NetBSD is so well documented. I'm a total amateur, I had to be handheld through the pull request since I have no idea how to use git. But with the problem itself, it just meant spending some time reading the source code for the syscall and thankfully the documentation in that syscall code being excellent. One day I'll have to figure out how to use git.
Considerations for "Readable & Maintainable" code: 0. Try to follow common practices for the language you are working in. Other programmers will be expecting this. 1. Try to keep related code together. Consider that someone may need to find something. 2. Try to stick to a consistent codeing style, and variable & method name scheme. 3. You may want to provide concise summary comments for code that is complicated, or unusual. Consider someone who understands the language, not necessarily the domain or project.
I finally, proudly say that I disagree with this take to some extent (Feels like I am now growing slightly). Readability is an essential item for me to consider when I am programming because I have worked on multiple projects back to back and having to context switch between those projects is hard for me so I write code in a way where it is as readable as I could so the mental burden of context switching is less. I get it that in due time you will truly understand the nuances of your project but being able to easily jump in and out of projects due to code redeability provides business value
I work with Mathematica. It is well known as a write-only language. The language tends to encourage the programmer to nest functions in functions which tends to make it very hard to read. I have plots blocks that are a couple hundred lines long and most IDEs would call that 1 line.
I like the way you talk honestly! Most people might think a good coder/programmer can read and maintain any code in a minute, especially their own code. When I look at code that I wrote (as a web developer) years before I sometimes think "wow! how the hell did I do this?" and "how does this work?". After rethinking some minutes it makes sense (so it's no magic) but maybe there's always other ways to solve problems. All roads lead to Rome. :-)
Downloading any project repository of moderate complexity and being able to directly read and understand the code without previous knowledge of the field and full context for the project is just a fantasy promulgated by self-appointment code gurus and middle management types. Every piece of interesting software assumes a lot of things that cannot and will never be documented. Not in the comments, nor the function or variable names, nor in some mythical external documentation. And this is for the most part a good thing. Writing useful comments or documentation aimed at a future unknown someone with unknown skill set and previous degree of involvement in the project is as futile as it is time consuming. Who wants to read the code for some cryptographic function with interspersed blocks of text explaining fundamental group theory?
there are 100% ways you can make code **more** readable. It's just another language like English, some people are eloquent, and some people are imprecise and hard to understand. "get good" applies to both sides of the argument on this one. Quentin in the video sounds like someone who writes hard to understand code. He uses word salad.
*Oh yeah there's a skill issue alright...* On the side of people who don't _know_ how to write maintainable code, don't even _understand_ the concept and *_don't even acknowledge its existence_*
poorly written code is just for example a function that is written in a way that it would need to be completely rewritten to add stuff to it. i had this with a small snake code. my moving logic function was written so badly that i couldn't add another condition to it or change anything inside it without rewriting it. it basically was just one big switch with additional internal if statments per case. so instead of first checking for availability of the direction before i ran the switch to change the arrays, i ran the switch first and then i checked inside of the case if there is the game border or not and if i need to wrap to the other side. my new function is not even half as long and is easier to read, to maintain and to expand.
Just because there is not a total linear order doesn't mean there is not a partial order. There can be things that are strictly worse for readability even accounting for different preferences.
Those people only think of the time they coded something and it worked so they must be geniuses. But if it had to be maintained, then it wasn't perfect or some feature had to be added, meaning the conext in which they coded wasn't complex at start. So yeah, readable and maintainable code is essential because the project does'nt stop the moment you leave.
Flat is better than nested Simple is better than complicated Complicated is better than complex Now is better than never Special situations are not special enough to break the rules. In the case of ambiguity refuse the urge to guess.
I really can't get over how much you're telling on yourself with this one. "I have this code base I can't understand in totality, but I can put print statements and fix bugs. That's readable" 😂 A readable implementation would have *shocked face* made the existence of that bug obvious so it wouldn't have made it into the commit in the first place.
You sometimes have to simplify your code in order to make collaborating easier. I worked on a huge Perl project with dozens of developers of which many hadn't been coding with Perl before. So we had to do things like, one liners are not allowed, using regex was discouraged and when used, had to be documented with a comment etc. This meant that we basicly wrote with a subset of Perl, simple syntax, more verbose code etc, just so we could guarantee that everybody in the team would know how the app worked.
In a previous coding gig I had a coworker that kept dogging on our old codebase while they never created anything new/useful. I had to call them out on it because it is useless to talk about SOLID or any other maintainability aspect if you don't have a codebase that profited enough for you to stay around and maintain it. At the end of the day, finishing something is more important than perfecting it. Computing/Programming is all about taking a problem and letting a computer solve difficult parts for you/your customer much faster than you/they can.
Out of curiosity are you in management? Getting code out fast is great but it comes with a cost. When you are so buried in tech debt and bad architecture that a rewrite makes more sense that is a huge cost. Everywhere I have been has these problems so maybe that is just how it is in the real world.
Well... that is partly true but if its not straight forward enough for the average developer in that language to understand its probably not readable enough...
My number one advice to mid-career and first-time senior developers: there's no objective definition of "readability," and "maintainability." These are concepts people care about and value but they're relative ones. Some times you do have to learn something new and as experienced as you are you might be surprised that you don't know everything yet. A lot of experience, wisdom, trade-offs, and considerations have been made in an existing code base... that you have to learn in order to be able to read the code and appreciate the idioms and patterns it uses.
Yo Prime ! This is one of your best vids. It's touching on a big question, i.e. get the grasp of coplex solutions. This can make one think about the birth of paradigms an of technoogies that shift paradigms, like Rust. After each of your videos i feel smarter. Thanks!
A problem with the phrase "readable code" is that when some people say it they mean "code that people can begin developing in with a small amount of spinup" and then some people mean "I was indoctrinated into the mindset that every single application ever written has to implement these design patters I was taught in school and everything has to be perfectly SOLID and DRY and use DX even if it doesn't actually need it and if you don't do all these things then nobody will ever be able to understand your code."
Maintainability is a very interesting word, because it literally means, you 'maintain' your code, but I think extensibility is a critical factor for maintainability. Yes, maintainability depends on the skills of the maintainer as well, but I believe this perspective somewhat relativizes the issue. Essentially, if there is a coherent and consistent logic behind the code, it becomes much more understandable and extensible, even if the underlying mindset might differ from yours. Fundamentally, it is coherence and consistency that render the code maintainable and extensible. The fundamental question becomes whether introducing new features necessitates substantial code rewrites, and if so, the extent to which lines of code need to be overhauled. Maintain your naming standards, assign responsibilities to each class based on the same principle, ensure clarity regarding what each method does, strive to use best practices, etc. This is how your code becomes easily maintainable.
".. just maybe, maintainability and readability is also a preference." I understand the point and I agree! There are individuals who may label code as 'unreadable' or 'unmaintainable,' simply because it's not to their liking. So in that sense, it is a preference! We could however make many experiments by taking two vastly different implementations and presenting them to various random groups of developers. There's a high likelihood that one of the implementations will be more easily grasped by most of the groups. The point I am trying to make is that 'readability' and 'maintainability' are not merely preferences - and they can be measured. However, they often appear to be just preferences, as a significant number of people seem to mask their own personal preferences behind these two terms.
One must walk a fine line between idealism and recognizing that perfection is practically impossible to achieve: on the one hand, without some sort of ideals to strive toward, no major improvements or paradigm-shifting developments will be made; on the other, getting bogged down in minutiae in a quest to perfectly embody a Platonic form is suicidal.
I've literally never had to make tradeoffs. I work for the government, and we never have deadlines tho lmao. We can just polish the project for however long we want.
Can it (readability and maintainability) only mean having some rules that the team has agreed upon? Like linting preferences or something that makes code more familiar when you're doing a code review of a junior dev.
The question should be "how much mental bandwidth would be required to follow what this piece of code is doing?" And you won't believe how big a difference descriptive variable names and function names make.
I think Prime hasn't seen enough terrible code bases to understand what an unreadable codebase looks like. Yes readability is subjective but if you have 20 lines of nested if conditions cause you didn't know refactoring was a thing and 20 lines of repeated code (but each line slightly different) cause you don't know how to use for loop then I would say most sane ppl would say that's pretty unreadable.
He is a lucky guy. If readability doesn't exist or just in the eye of the beholder, then why are we keep linting, styling, syntax highlighting, structuring, designing the code?
Nothing matters if it works, right?
I do accept that it is highly subjective and it is based on context, but that's why languages has their own styles that people follow and judge code on. Yes, it also depends on what the business requirement is, for example I think the Linux kernel code is highly readable, well designed for what it has to do. But from a simple webapplication we can expect even higher standards of readability, since its code is not as critical and better aesthetics are easier to achieve.
That's what it looks like. To me, a terrible code base that has some wild side effects like a code base that uses both Angular and jquery to modify the DOM and on top of that use "any" for all type annotations
Exactly! I think Prime and most of the comments here haven't read *actual* bad code. Not complex code that solves complex problems, not code in languages/frameworks you're not familiar with. Just simply bad code.
Im talking about simple python scripts written in a way that look like assembly, global variables that are used loosely, functions inside of functions inside of functions that each of them are called just once, bad names for everything, functions that alter global variables with no warning or documentation whatsoever, repeated code in multiple places that could've been easily extracted into a function, endless nesting, condition's being checked multiple times for no reason...
Basically the opposite of what any sane codebase would do, usually for lack of experience, or an abundance of doing things on your own way (aka Tom is a Genius syndrome)
Sometime "bad code" doesn't mean ugly code, or complex code, or poorly optimized code, it simply means plain bad code.
While I am not entirely sure prime has seen truly stinky code, I agree with your take.
I think there are certain code practices that we can (mostly) agree decreases readability of the code to whoever is reading it, one example is code with high cyclomatic complexity
I have seen those codebases and the answer as a maintainer is:
- Put a test there
- Eat the elephant one bite at a time.
With enought sweat tears and weird slightly erotic dreams that you wake up from scared about what you have discovered about yourself...
You can get it down to 18 lines of nested ifs. And that's a lot better.
The first nested ifs are often the hardest to fix.
I literally screamed when I saw the primeagen reacting to tsoding. I've been waiting this for ages.
OMG it's happenninnnng
I screamed without the s
WOAOW IT'S A UA-cam MAN IN A UA-cam BIDEO MOM CANCEL MY MEETINGS
@@vikingthedude I did both screamed and screamed[1:]
@@youtubeenjoyer1743 Yes 😎 monkey neuron activation
Sometimes when I look at my own code I go "why the hell did I do it that way". Then when I try to fix it I go "oh, I see" and regret that I'm still unable to do it any better.
I just love Tsoding
He needs some sunlight
He needs lot of thing but yeah sun light is part of it. @@nkristianschmidt
A company is still using a piece of code I did 3 years ago, when I went back and saw it was still used a lot and I could still read it, I felt really proud of myself ngl even though it was most likely an accidental W.
For me writing readable code means to not use complicated patterns, syntax or control flow until it’s needed. Yes code for complex issues will be hard to read, but most times that’s only a small part of the Application. The rest can and should be simple!
Generally good. Also helps the compiler do the good crazy stuff for you. With complex language features you usually add code for all the complexity the feature should handle.
When it comes to code i try to live by the mantra - "As simple as possible, but no simpler".
Pretty much just another way of saying the same thing as you
Yes, readability is subjective, but that doesn't mean it's not a real thing to achieve. In general, one should try to write code with an eye to someone else having to come in and add features or fix bugs. Even if your code is perfectly flawless, you want it to be OBVIOUS that it's flawless so that the reader can continue on to the next section of code on the suspect list.
This is a different discussion than "reading other languages is difficult" or "understanding an entire interconnected system of code is difficult". You're taking these very different topics and calling it "readability".
And yes, sometimes, the issue is that the individual coder trying to read the code isn't that bright, or too new. This is why most code bases have "new, simple features" coded by cheaper mid-level coders, while the senior coders are tasked with solving the problems that those less-skilled coders created. The less skilled coders don't have the skill to parse out such problems, yet. But this isn't a "readability" issue, nor is it a subjectivity issue. It's just a skills issue, which doesn't preclude readability as being a reasonable goal, especially for senior coders. In particular, senior coders should focus on keeping things simple and readable so that the newer coders can be tasked with fixes and upgrades, so the senior coders can focus on more advanced work.
"The maintainability of the code also greatly depends on the ability of the person to maintain."
Fancy way of saying 'skill issue"
Which is kinda missing the whole point.
The point of "write maintainable code" is to get devs to think beyond "it compiles" mentality.
(Edit: typo)
What about poorly designed systems?
Not a skill issue when you fighting the code base all the time and piling on more technical debt with each iteration as a ripple effect.
Not a skill issue when you waste time trying to make sense of the code because previous devs used arcane naming conventions, patterns and did not follow standards.
imo
Sometimes the system is poorly designed. And sometimes it's a skill issue between the reader g and the code. If you're not familiar with concurrency and multi-threaded programming, you're going to have a bad time debugging race conditions.
Just because concurrency is hard to get right doesn't mean it's wrong to use it, and the code should be rewritten for some junior to understand in a linear fashion.
@@edwardcullen1739 the point is that to write code such I can come back and be able to understand what the heck is going on without having to spend a week picking up esoteric skillset to do that. But some "smart" folks think that esoteric skills is what makes them good as opposed to ability to express complex ideas in simple enough manner that doesn't need esoteric upskilling to participate.
@@sk-sm9sh Amen! Couldn't agree more!
This is like saying that what words I use in my sentences doesnt matter, you can use any words and any words can be as descriptive as any other words, because language is subjective.
you cant can't simply ignore the importance of word choice and sentence structure. Language can be subjective but there are shared conventions and meanings that allow me to convey my thoughts more clearly.
I assume that you are talking about readability, but not sure what is the point of your analogy. 'word choice' is about semantics, while 'structure of sentences' is about syntax. The same way a compiler can't understand a program with syntax/type errors, you can't understand poorly worded/structured sentences. Those things are not about readability, but about understanding, about the meaning. In your analogy, readability would be the type of font that you use, font size, formatting, text color, etc, which you would probably agree are highly subjective and do not affect the meaning of the sentences. Readability is about being able to parse code, not understand it. And that's why it's mostly up to your preference.
@@clawsie5543Completely ignoring the intentions insydium's argument in bad faith, nice one.
@@clawsie5543lmao, no. The structure of a sentence directly affects readability.
Eeeeexexamplö for I mean ye somewhat may that little be harder to well read but under… standable?
This sentence is a mess that is hard to read but you can understand it after some thinking. Bad code is the same
TSoding is a beast and Prime is a beast. So this is a certified double beast moment.
and only Tom is genius
Finally, the historical moment!
welcome to reactions to another zozing session
The beast with two backs
And yet they suffer the "good programmer syndrome": They genuinely don't understand that their code still needs to be able to be understood (and modified without breaking something undetectable) 10 years from now, by people who were not there when the system was designed and barely understand how it works.
The missing aspect of readability is understanding the data that code may be operating on. Without this context, I can really struggle to understand what the code is doing.
So basically you are saying that type annotations help understanding the context and thus makes it easier to understand the code?
@@sk-sm9sh I think what he means is, you need to understand the domain itself, how data is related to each other. Not the data types, etc, thats still code.
@@Baby4Ghost now try understanding how data is related when you can't even understand what the data is in code that has no type hints...
@@sk-sm9sh ah, i understand what you mean, you are talking about weakly typed languages, correct?
in that case, i concur, thats why i strongly prefer to work with strongly typed languages.
but to find out how data is related is very easy, you ask any person that works/worked on the project to explain what its supposed to do. aka, the context Joe(opening post) is talking about.
understanding what the program should do (context), and figuring out how the program works (code), are sometimes not aligned. when you know both, you can figure out a way to go forward.
Ever dived into code with #ifdefs nested every 5 lines? Or stumbled upon files where every line is sprinkled with 10+ magic values and intricate bit manipulations? While coding styles vary, there's no denying: readability isn't always subjective.
Agree. Well, someone might come along here and say that there are people who can read this kind of code quite well actually. But even if someone has the experience and skills to read such code, it doesn't mean that the code itself has become more readable. It's just that "you" who have learnt how to read poorly written piece of mess instead of code.
Can you define readability for that piece of code without taking into account your preferences?
@@tokiomutex4148 I mean magic numbers are objectively bad since you have to know what they represent to understand the code. If it's a constant with a decent name at least you have something to go on.
is there way to structure your functions so that they are easier to understand? Yes.
Is there way of naming variables and functions so that they are less confusing? Yes.
Is there a way to structure your codebase so that its easier to understand? Yes.
See? You can make your code more maintainable even if your problem is difficult.
What if the answer to all those questions was a no? try writing a compiler for Haskell that is a readable why, in Assembly.
@@chudchadanstudAssembly language is not a high level programming language. Using it here is a strawman argument
@@MachineYearning okay, do it in APL.
Also maintanability can be also measured.
Easier to understand to who though? I work on a smallish team, and we have a micro services based codebase that spans everything from low-level embedded and signal processing code in C/C++ to standard backend web-server business logic code, to web UIs, and I think what is "readable" is very very different in each area.
If you are doing something that leans heavily on maths or comp sci theory, you might have lots of functions with mostly one-letter variable names, because that is the most readable way of writing that function IF you have the background in theory to understand it, because all the textbooks and papers will be using those same letter names for the same things. And you can probably assume that if someone isn't familiar with the underlying theory they shouldn't be editing that code. Conversely though using lots of one-letter variable names for anything that isn't a simple loop counter is a code-smell in most other code. But always you will run into the problem where people who could read the code if the variable name was "radius" not "r" then find it difficult to read when they need to read it for context. How do you balance those things? If I have to split one common mathematic expression over 5 lines of code because I have huge expressive variable names that spell everything out it becomes less concise and harder to verify by inspection, sometimes.
Likewise for people who spend all day writing C-style code, they are very used to seeing and writing raw loops, in a way that is highly discouraged in modern C++/Rust where iterator/algorithm statements are considered far more idiomatic. But which group of people is going to read your code? And if it is both groups, for code on the boundary, whose is "more readable"
Readability always depends on the domain, and the language, and the person reading it. There are maybe a small subset of rules where we could probably find everyone agrees (nested if statements are bad, so on), but it's not a huge list, and lots of them have qualifiers. Almost everyone agrees small functions are better, but how small? 50 lines? 30? 5? Maybe the function should "do one thing", but what you consider to be "one thing" can vary.
I write lots of Rust, and I have a colleague who writes lots of C#, and both can be used for simple web-server code quite efficiently. He reads my rust and finds all the odd symbols and the requirement to mentally keep a bit of a tab on where ownership is flowing and what the code will boil down to onerous and thinks it is difficult to read. I then read a similar web-service he has written in C#, and stumble around reading 600 lines about IThingies created by IThingyFactories sending IMessages to AbstractWhatsits and get annoyed because I can't find the 20 lines of code that actually do the work. But other people on the team who have systems-level code backgrounds find my code easy to read because lifetimes aren't really that hard (most of the time) and its natural for them to think about what code boils down to, and others who have OOP backgrounds find it really easy to digest the top level class hierarchies and enjoy feeling productive as they do all the busywork of unit-testing all their boilerplate. I don't think you can really objectively say either one is "more readable", one is more readable to me, one is more readable to him.
I think if you are working a particular sort of problem, and your code will be read by people with similar backgrounds, experience and skills as yourself, and you are all working together for some time and have built up the same library of idioms and patterns, it is quite possible to define what is and what is not readable. But how often does that happen in any code base that is non-trivial?
If you're progressing as a developer, then the "what idiot wrote this?! Oh, me." moments are unavoidable. You're going to be learning things you didn't know before, which will change what you use and when you decide to use it. I'd honestly be more worried if I look at a lot of my old code and think "yep, absolutely perfect, this person is a genius."
I have gotten to the point where it's more like...
"Oh, that wasn't nearly as dumb as I feared it was going to be" and I'm not sure if that's a good sign or not.
@@HrHaakonthat's one of the most unnerving questions, we don't know if we're plateauing at a good level or just not improving and not realizing that
I think it can be broken down into a few stages.
- You see no problems in your old code, because even though you had no idea what you were doing then, you still have no idea what you're doing now.
- You see nothing but problems in your old code, because it was complete garbage and you're now skilled enough to not write complete garbage.
- You see nothing but problems in your old code, because even though it wasn't garbage, you're now skilled enough to make a lot of improvements.
- You see nothing but problems in your old code, because even though it's completely fine, you've changed your coding style and no longer find it aesthetically pleasing.
I disagree. You should maybe do this early in your career. But if you constantly think code you wrote 3, 6, 12 months ago is bad, that means you're likely still writing bad code - because in all likelihood you're calling code bad if its just unfamiliar and not in your current preferred style.
You're not improving, you're running in circles.
I did that with a Wikipedia article recently, turned out I wrote the original article nearly 20 years ago lol.
This is the same philosophical domain as "I apologize for the length of this letter. I didn't have time to write a shorter one."
To me, clean code is about not adding incidental complexity and making the inherent complexity of the problem being solved as obvious as possible.
It's certainly subjective where you stop of that scale right now, but many objective scales have been developed, e.g. big O.
when 2 universes collide
Tsoding is a coding God. Learned so much from him with thinking about programming and coding in general.
One of the most valuable resources in YT on my learning path. Still watch all of his videos, mostly on the second monitor. He's excellent at explaining all the concepts and keeps it real without smashing in thousands of frameworks etc.
@@QckSGaming Agreed. Something I always hated about tutorials that were supposed to teach you a specific concept was how many times they resorted to just slap library functions on a few lines of application code
Real
Agreed. Largely discovered my love for C through him and the pursuit of mastering something even if it is hard, and grew a ton as a programmer.
As always, the key word is consistency. You'll have to get used to the codebase anyway, but if the style is consistent the process will be far easier.
Usually, the person writing the code will be better than the person who will have to maintain the code.
True skill is the ability to take complex ideas and express them as simply as possible. A mid-tier fresh graduate should be able to read and comprend your code.
The issue is when you have "god tier" devs who write code that's beyond all human comprehension.
It's part of the idea that developer responsibility extends beyond "I checked it in and it passed the compile check".
If ya can't read it ya can't maintain it.
Increasing readability of a language, leads to --english-- I mean COBOL
Increasing maintainability leads to a language with builtin documentation, so lisp
I love Lisp, so im probably biased
Based take
I love apl and lisp and even if they appear impenetrable they make complete sense to someone that just took the time to understand the language. People have very shallow views about what readability/maintainability is or should be
Both can be objectively measured.
Readability Is a ratio between "need to know first" and "now can read the rest". You can think of it as a time to onboard a new programmer compared to lines of code in the app.
Maintainability is similar, because it's again about how much you need to know and how many lines you need to touch to add a feature, or fix a bug.
If your average junior can navigate your codebase after a short onboarding... it's readable. If he can work with it effectively, it's also maintainable.
The only measurement guideline that is reliable for both being bad is when someone says they can be objectively measured.
If such things could be predefined for objective measurement programmers wouldn't have a job.
Neither code readability or maintainability of code can be objectively measured, only subjectively interpreted.
Readability is always subjective since the text in each part of it's own ratio cannot be predefined for evaluation in a test only evaluated as someone re-reads it later.
Maintainability is only measurable AFTER it's been maintained but it cannot be evaluated because there is nothing to compare it to was we don't have access multiple universes.
"If your average junior can navigate your codebase after a short onboarding...", Basically, it is a toy project.
@@TheNewton Readability is subjective for YOU, since it's based on YOUR knowledge.
You can read English books, but you cannot read French ones for example. They are different for you, even though their readability is basically same.
The same applies for say Russian books, because they simply have a different character set. Again, something that you need to know, or learn, but Cyrillic isn't harder than Latin.
Then, there are Japanese books, which are objectively harder, because they have symbols for words, so to read (not even translate) their texts, you need to learn those thousands of symbols. To learn their language in general, you'll need to learn both the word and it's visual representation.
So, we've established a very tangible difference between some languages and Japanese. Reading Japanese is OBJECTIVELY harder.
The same applies to languages themselves (how many rules you need to use to build up a sentence, for example).
The same applies to every book (how obscure words and how obscure sentence rules are used in the text)
Etc.
Therefore, even the readability of a source code is measurable. There is no practical difference. It either uses the "minimal and typical" set of features to do the thing, or it uses obscure constructs for it. (what is typical and what is obscure can be statistically analyzed through scanning of a github, for exmaple). It is either consistent with naming, with project hierarchy, etc. (so that you can learn it on one part and apply it on another), or it is not. Again, measurable. Etc, Etc.
And for what it's worth, there are a plethora of valid reasons why make something less readable. But it's still less readable.
@@jamesm4957 Yes, they tend to be readable indeed. I didn't say, nor imply that a large codebase must be readable by junior. It might be unreadable for many reasons (long running project with several generations of code in it, performance reasons, hacks, different teams with different philosophies, etc). That being said, It still ends up being harder to read and we can almost quantify it.
I think we're moving from one extreme to another with this video.
Yes, the "maintainability and readability" is not a code author's responsibility only* and yes - the experience of the programmer that will need to read/contribute/maintain it also matters
But we can't also just say, that I will write whatever I want and however I want ... and put all of the responsibility to understand the code to new programmer all by himself
It's like Tsoding said - it's a double-edge sword. Author is responsible for creating most straight-forward code possible (since there are always a trade-offs, so sometimes code will not always be straight-forward... especially for some serious/complicated stuff) and help new contributor to understand it.
New contributor on the other hand is responsible to adapt to it, despite his preferences. If he doesn't like the style or a way in which this code was written, he will fit better somewhere else. Somewhere where code meets his preferences and he will feel more comfortable and the learning curve will not be too high to overwhelm him
"The maintainability and readability is not a code author's responsibility" is literally a justification for "I will write whatever I want and however I want ... and put all of the responsibility to understand the code to new programmer". It absolutely is the author's responsibility.
Reading code is often as hard or harder than writing code IME. It's an overlooked skill.
Well not necessarily true what you say. You can try to write code that is easier to read than to write, if you embark on this task then it alone makes it pretty damn hard to write any code :)
Prime reacting to and agreeing with Tsoding?? My life is complete!
hell yeah, tsoding feature
Unmaintainable code is real. It's out there. And it will find you. And when it does, then you'll regret telling people that it's not their responsibility to think about readability when they write code.
This is a very poor mindset to have, "The maintainability of the code also greatly depends on the ability of the person to maintain." is just giving him an excuse to write crap code then say other people have skill issues. A skilled programmer can simplify problems. Sure if you have a high complex problem, it will be harder to understand but it shouldnt be hard to read. Its a massive problem when a dev has a very simple problem and thinks he is smart and builds the most complex solution in the world.
Readability is basically a measurement of someone's ability to keep their code simple. Your code is poorly readable if I can take it and do it in fewer lines with less indents, fewer function calls, with similar lines grouped together, and better named variables.
The take that readability is a skill issue is true but only for the person who wrote it not the person reading it. Your code should be as self explanatory as possible with comments explaining where it is not.
I was about to post a long description of the nightmare app I took over at my new job to get some advice or validation or something ... but it's description wasn't even maintainable.
I'll just add that a big part of 'maintainability' can have a lot to do with overall architecture, especially when you're a team of only 1.
What do you mean "readability doesn't matter"? That's like saying it doesn't matter that books be readable.
In fact, I often write code as though I'm writing a children's book. If I showed my parents this code, could they grok it?
Your code should be written so the steps of the algorithm are clear, and there should be established rules that must be followed (if they can be enforced via linter, great) to ease readability and maintainability.
i may be in a ts and js space, but the comment of "go pull up any github project and read it, its gonna look bad" i completely can not agree with this. I have spent dozens of hours reading people's code on github and there is a clear difference in how easy it is to understand the architecture of the program. Some people know how to write code that is easier to work with. we can not deny that, and in itself this is a skill.
Readability can be proved through A/B testing. Implement function in 2 styles, get a survey on random engineers, and measure how fast they can figure out the right answer. And unless result is 50/50 in which case it just means doesn't matter and best way to solve is to toss a coin if however outcome is 20/80 there is clear benefit to one style over another. We just didn't figure out to do that for some reason yet. Instead we typically make decisions based on opinion of someone who's going to stick through flame war the longest and who uses the most inventive rethorics basically somewhat same way how we politicians develop laws. Which is not always the best thing for majority.
I disagree with this when working in a team level, if the code is not readable is hard for others to maintain.
I had see TS codebases full of any's and without documentation, if is a skill issue to maintain that, I don't think I will reach that level.
Complex code can be readable, but other code is not readable because someone do not care about it.
Most people watching this won't realise that prime is in a very rare position in the industry, being able to choose how he formats his code.
Most programmers who work in teams for companies (that aren't startups) will already have established practices for coding conventions, linters and senior Devs to check that the code follows them. That prime didn't mention any of these once means he definitely didn't go through the route that most of us will take.
Yeah, I have only been coding professionally for a few months, but the best projects were definitely ones where even just onboarding didn't require me to get used to seven different people's preferences and coding styles
@@TomNook. Yeah, I've never been able to use my preferred style (which is objectively better, obviously 😉) because someone else has already defined a style I need to adhere to.
@@edwardcullen1739I had see projects with different styles but they had linters, rules and good PR reviews you need to follow.
So no matter your style, if you follow that the code will be maintainable not matter your style, that's the way to go
@@neociber24 Humour lost in translation, I think...
Maintainability goes far deeper than simple styling issues.
Programmers need to read some philosophy of language like Wittgenstein. This question is answered by Wittgensteins concept of language games and communities of knowledge.
Also, there is a third perspective, its just subjectivity and objectivity - there is inter-subjectivity and thats what these discussions by programmers always miss. Conventions exist.
😬Sorry bro but you're wrong about this (with all due respect!).
If the code is not maintainable and readable, it's not reliable or suitable for anything "mission-critical." It's more difficult to understand & fix bugs, and it takes much longer to implement new features.
You have a bit of a not-customer-facing perspective.
Someone has to explain insecure communication protocols, weird UI choices, inconsistent & unpredictable behaviors, system failures, data-corruption & data-loss, patch-application procedures, painful upgrade paths, lack of requested feature support, lack of device support, etc. to partners, distrubutors, OEMs and end-users.
Yep, totally! Alcohol content in your vodka depends on your alcohol tolerance 😂 seems like a smart’s person excuse to produce working, but shitty code
There's some simple things people can do to improve code readability (and therefore maintainability) that they don't do - like give variables appropriate names, have consistent whitespace etc, basically stuff that is entirely cosmetic in the code. That stuff is important to get right and has no downside.
I think sometimes people end up being told that readability is about making sure a junior dev can read their code though, and in some applications that's okay, but sometimes you end up with people using slower/less space efficient implementations of things just to make the code more simple to understand, and in those scenarios you have to think about whether it's worth it.
Like when you take the famous Quake inverse square route function - that code isn't 'readable' at all, but it did the job it needed to do perfectly.
JDSL is readable, we just dont have the skills to comprehend it
TBH. I'm NOT 100% onboard.
With so many things in software it's often a question about the average skill level of the team, not a single dev.
Codebases using a bunch of service patterns and God forbid an AbstractFactoryFactory is perfectly readable for a team of seniors.
A team of juniors would probably just give up. If You're the only senior in a team of juniors it's your responsibility to write the code in a manner that your TEAM can support this. So it has to be readable and maintainable for them.
The definition of readable and maintainable depends on the team setup. Same goes for complexity
Readability to me is using correct indentation, not using weird abbreviations for names, not trying to be crafty with pushing as much stuff as possible in a single line and adding the comment here and there to communicate the intention. Add to that that functions should be kept down to a reasonable length and not be nested too deep. I'd put it in a single line as: don't be a show-off.
I modified the code of Dmenu by hand and it changed me.
Dmenu is designed to be good for it's scale, exclusively. Globals, few files and functions... Also, it's designed to work well in the context of low level C.
I didn't get that and started refactoring it, and then it occured to me.
If you want to scale it, then take odeas from it and start from scratch.
I had never thought this way before! I thought code is this balloon that you stretch to it's limits and deflate into a maze like heavy mess as you're going up and down in scale with it.
Nowdays I write code that's readable by the person who understands code written for the current scale of the project.
Maybe that's bad, but wow, this is a way more complicated notion of readability. Thank you Dmenu!
this just reads as im too lazy to think of good descriptive variable and function names and easier to understand way to structure my problems
If you need an explanation of 10:00, look no further than 12:40. Basically, "There is no direct and simple prescription (linearity) for everyone to understand. Instead, there are a lot of interconnected ways to look at a big project, and the approach will vary person-to-person. So there should be considerations that make sure no matter what ways (multi-dimensionalness) a person analyzes the codebase, whatever insights they get should reinforce each other (diverse entrypoints) to build understanding - even if it's done in the readers' own chaotic and unique way, even if they have imperfect information (lossyness) on the theories involved."
Tossing and Prime in one video? This is amazing.
5:00 I think that is exactly what maintable code is. You do not have to know or understand the entire Code base. But you know exactly what Kind of Inputs should lead to which Kind of outputs, so you can still fix and improve it.
But this also requires readability, in the sense that the code is documented well enough (or self documenting) that you actually know the exact Inputs and Outputs, what Kind of errors may occur and these might be handled.
There are several factors to readability and maintainability.
Try reading minified or obfuscated code and see if that is maintainable :). Compare e.g. the original Obfuscated Tiny C Compiler with the initial unobfuscated version checked into the Tiny Compiler repository. Using sensibly named variables and a consistent formatting help a lot in readability, especially coming back to code after a while.
Being unfamiliar with programming languages, libraries, programming styles, etc. make code harder to read, but as stated those can be solved by learning those.
Adding comments to explain an algorithm, or link to external descriptions of those, can also help. Especially when you have things like the complex nested for loop matrix multiplication optimization. Having something like "process the next 2x2 submatrix" and "invert traversal of matrix B to align with cached reads" will go a long way to help understanding that code later down the line when you have forgotten the specifics, or someone else is looking at the code wondering what the hell it is doing. It doesn't need to be a PhD thesis, just enough to give the reader context on what is happening if that is unclear from the code.
Good code is like literature. For the first 100 pages of Dune you don't know wtf is happening, but that is because it is *good* and doing complex things with great skill.
Is it subjective? sure. Can some subjective things be better than other subjective things? absolutely.
Why not name functions in Chinese (oh you can't read it? skill issue.)? why use linters and code formatters? why not just put all the files in the root directory (or better yet, just put them in a single file)?
I don't think it's a good take, Prime.
Yeeted at 2 min. The reality is, in any kind of collaborative environment, you are going to have programmers of all different skill levels looking at a given chunk of code. Choosing to optimize the way you write code for accessibility, favoring common paradigms that other engineers are likely to be familiar with, establishing standard implementation patterns throughout your codebase -- these are all worthwhile efforts with good ROI.
There's complex code and just bad code. Most people think bad code is un-readable and un-maintainable. Complex code _when that complexity is necessary_ is generally fine
I started working on a project which codebase is impossible to follow. The original developers left the project and nobody in the team fully understands how the project builds and deploys. It is just beautiful.
The best crossover in the history of anime
When I have a task that can be implemented as a long chain of maps and filters, I usually break it up and have intermediate fully typed variables so that I'm not only trying to limit the size of the mental stack required, but also allow the type inference to not break for the entire chain when I'm working with it. I try to limit my complexity budget where I can and so if I do something clever I try to make that the only clever thing in that bit of code. This helps me avoid writing code that I'm smart enough to write but not smart enough to understand when reading later.
I was waiting for ages for you to start looking at tsoding's stuff, HE IS A LEGEND !
If readability doesn't matter why don't we optimize code for compiler speed? Shortest variable names possible and minimize whitespace (no new lines or tabs). Just put all your code in a single line of a single file.
Obviously, there are good reasons to sacrifice readability. Sometimes complex problems need complex code. However, just saying that anyone can write in whatever style they want and telling everyone with a problem with that "skill issue", is absurd.
I like to write one line if statements. Like this
if (some_int > 5) return some_int
if (some_int 5 => some_int
case x: int if some_int something_else
}
That was okay, because it wasn't an if statement, it is a match statement and that's how you just write match statements in Scala. And therefore this is readable, but one line if statements are not...
In the code I write, especially in the newer ones, I always try to add an explanation to introduce the next person to the mental model I thought when I wrote that code. By doing that way, my code might not be very very well documented (sometimes I forgot a few things or add some whys, or even to end a phrase) but I want to allow them to get into my mind. Of course, to keep the code readable, I also adopt other precautions.
Industry standards for personal code and industry + maintainer standards for team code. Years later you’ll still be able to quickly understand/ modify it even if you moved on to another language
Lots of ‘geniuses’ who’s code, no matter how simple, are an enigma simply because they can’t be bothered.
Tsoding shows that persistence is key. I used to stream coding on twitch too, I even had more viewers than him at one point. He kept going for a long time before his numbers started to raise
Maintainable and readable code is easy if you put the work into it.if you know your code works and you've covered your code with tests you can make it more readable by renaming variables properly, extracting parts of the code to methods or classes. Write, test, refractor.
You can have the greatest story for a book but when your sentence structure is so illegible so that others can understand it you're not a good author.
Practicing a profession means adhering to common standards and making your work as understandable for others.
Readability is a real thing when you have some hotshot developer that wants to write everything as code golf and develop his own unique syntax for traversing arrays, or special snowflakes that want to make their interface different from 30 other ones that are all identical. But how hard their code is to read is not really the issue, but rather their inability to work in a team like a normal fucking human being.
It's why I never get annoyed at too many comments (If it becomes obnoxious they can easily be remove), but get eternally frustrated by the hubris of some programmers to never leave a single comment.
I understand that it might offend some people's sensibilities to have their code base littered with comments, but I think it's even worst when working in a team of developers on a project to expect to understand some horrible deeply nested if statements (That might be necessary).
I've been told I comment too much sometimes, but the amount of time people have appreciated the facts I leave comments in comparison to parsing "Tom's" code uncommented code is staggering.
In my mind, if i need to comment a line of code, i've failed at my job.
Regarding the thing about spending the time to learn what's going on, that's kind of what I did with an OSS program that was broken when making some syscall on NetBSD (It was some component of i3 window mgr I think). But it definitely helped that NetBSD is so well documented. I'm a total amateur, I had to be handheld through the pull request since I have no idea how to use git. But with the problem itself, it just meant spending some time reading the source code for the syscall and thankfully the documentation in that syscall code being excellent. One day I'll have to figure out how to use git.
Considerations for "Readable & Maintainable" code:
0. Try to follow common practices for the language you are working in. Other programmers will be expecting this.
1. Try to keep related code together. Consider that someone may need to find something.
2. Try to stick to a consistent codeing style, and variable & method name scheme.
3. You may want to provide concise summary comments for code that is complicated, or unusual. Consider someone who understands the language, not necessarily the domain or project.
I finally, proudly say that I disagree with this take to some extent (Feels like I am now growing slightly).
Readability is an essential item for me to consider when I am programming because I have worked on multiple projects back to back and having to context switch between those projects is hard for me so I write code in a way where it is as readable as I could so the mental burden of context switching is less.
I get it that in due time you will truly understand the nuances of your project but being able to easily jump in and out of projects due to code redeability provides business value
I work with Mathematica. It is well known as a write-only language. The language tends to encourage the programmer to nest functions in functions which tends to make it very hard to read. I have plots blocks that are a couple hundred lines long and most IDEs would call that 1 line.
I like the way you talk honestly! Most people might think a good coder/programmer can read and maintain any code in a minute, especially their own code. When I look at code that I wrote (as a web developer) years before I sometimes think "wow! how the hell did I do this?" and "how does this work?". After rethinking some minutes it makes sense (so it's no magic) but maybe there's always other ways to solve problems. All roads lead to Rome. :-)
Downloading any project repository of moderate complexity and being able to directly read and understand the code without previous knowledge of the field and full context for the project is just a fantasy promulgated by self-appointment code gurus and middle management types.
Every piece of interesting software assumes a lot of things that cannot and will never be documented. Not in the comments, nor the function or variable names, nor in some mythical external documentation.
And this is for the most part a good thing. Writing useful comments or documentation aimed at a future unknown someone with unknown skill set and previous degree of involvement in the project is as futile as it is time consuming.
Who wants to read the code for some cryptographic function with interspersed blocks of text explaining fundamental group theory?
there are 100% ways you can make code **more** readable. It's just another language like English, some people are eloquent, and some people are imprecise and hard to understand.
"get good" applies to both sides of the argument on this one.
Quentin in the video sounds like someone who writes hard to understand code. He uses word salad.
*Oh yeah there's a skill issue alright...* On the side of people who don't _know_ how to write maintainable code, don't even _understand_ the concept and *_don't even acknowledge its existence_*
poorly written code is just for example a function that is written in a way that it would need to be completely rewritten to add stuff to it.
i had this with a small snake code. my moving logic function was written so badly that i couldn't add another condition to it or change anything inside it without rewriting it.
it basically was just one big switch with additional internal if statments per case.
so instead of first checking for availability of the direction before i ran the switch to change the arrays, i ran the switch first and then i checked inside of the case if there is the game border or not and if i need to wrap to the other side. my new function is not even half as long and is easier to read, to maintain and to expand.
What is code quality then? Can we tell that the only objective measure of it is simply of many bugs emerge from it ?
20min rant after perfect explanation you accepted. Shit sits deep I know. Sending hugs
Did anybody notice the "Porn Folder" text?
"Can't maintain a codebase written in Brainfuck? Skill issue."
Not IS subjective. CAN be subjective! Show me how "magic numbers" should be accepted as "readable".
Just because there is not a total linear order doesn't mean there is not a partial order. There can be things that are strictly worse for readability even accounting for different preferences.
Those people only think of the time they coded something and it worked so they must be geniuses. But if it had to be maintained, then it wasn't perfect or some feature had to be added, meaning the conext in which they coded wasn't complex at start.
So yeah, readable and maintainable code is essential because the project does'nt stop the moment you leave.
Flat is better than nested
Simple is better than complicated
Complicated is better than complex
Now is better than never
Special situations are not special enough to break the rules.
In the case of ambiguity refuse the urge to guess.
I really can't get over how much you're telling on yourself with this one.
"I have this code base I can't understand in totality, but I can put print statements and fix bugs. That's readable" 😂
A readable implementation would have *shocked face* made the existence of that bug obvious so it wouldn't have made it into the commit in the first place.
Any, my boi тфодинг is finally here!
This is the most relatable take I’ve ever gotten from prime. I want to incorporate this into my mantra.
3:20 win activation code in the chat. Lmao, based.
lol i realized it now hahahahaha
You sometimes have to simplify your code in order to make collaborating easier. I worked on a huge Perl project with dozens of developers of which many hadn't been coding with Perl before. So we had to do things like, one liners are not allowed, using regex was discouraged and when used, had to be documented with a comment etc. This meant that we basicly wrote with a subset of Perl, simple syntax, more verbose code etc, just so we could guarantee that everybody in the team would know how the app worked.
In a previous coding gig I had a coworker that kept dogging on our old codebase while they never created anything new/useful. I had to call them out on it because it is useless to talk about SOLID or any other maintainability aspect if you don't have a codebase that profited enough for you to stay around and maintain it. At the end of the day, finishing something is more important than perfecting it. Computing/Programming is all about taking a problem and letting a computer solve difficult parts for you/your customer much faster than you/they can.
Out of curiosity are you in management? Getting code out fast is great but it comes with a cost. When you are so buried in tech debt and bad architecture that a rewrite makes more sense that is a huge cost. Everywhere I have been has these problems so maybe that is just how it is in the real world.
Well... that is partly true but if its not straight forward enough for the average developer in that language to understand its probably not readable enough...
My number one advice to mid-career and first-time senior developers: there's no objective definition of "readability," and "maintainability." These are concepts people care about and value but they're relative ones. Some times you do have to learn something new and as experienced as you are you might be surprised that you don't know everything yet. A lot of experience, wisdom, trade-offs, and considerations have been made in an existing code base... that you have to learn in order to be able to read the code and appreciate the idioms and patterns it uses.
maybe a collap in a future video with tsoding ?
7:10 it’s not just readability that can be based on preference. I think how you code up and encapsulate complexity can be based on preference too.
Yo Prime ! This is one of your best vids. It's touching on a big question, i.e. get the grasp of coplex solutions. This can make one think about the birth of paradigms an of technoogies that shift paradigms, like Rust. After each of your videos i feel smarter. Thanks!
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."
Clean code starts with clean requirements.
A problem with the phrase "readable code" is that when some people say it they mean "code that people can begin developing in with a small amount of spinup" and then some people mean "I was indoctrinated into the mindset that every single application ever written has to implement these design patters I was taught in school and everything has to be perfectly SOLID and DRY and use DX even if it doesn't actually need it and if you don't do all these things then nobody will ever be able to understand your code."
Maintainability is a very interesting word, because it literally means, you 'maintain' your code, but I think extensibility is a critical factor for maintainability. Yes, maintainability depends on the skills of the maintainer as well, but I believe this perspective somewhat relativizes the issue. Essentially, if there is a coherent and consistent logic behind the code, it becomes much more understandable and extensible, even if the underlying mindset might differ from yours. Fundamentally, it is coherence and consistency that render the code maintainable and extensible. The fundamental question becomes whether introducing new features necessitates substantial code rewrites, and if so, the extent to which lines of code need to be overhauled. Maintain your naming standards, assign responsibilities to each class based on the same principle, ensure clarity regarding what each method does, strive to use best practices, etc. This is how your code becomes easily maintainable.
Welcome to Costco
".. just maybe, maintainability and readability is also a preference."
I understand the point and I agree!
There are individuals who may label code as 'unreadable' or 'unmaintainable,' simply because it's not to their liking.
So in that sense, it is a preference!
We could however make many experiments by taking two vastly different implementations and presenting them to various random groups of developers.
There's a high likelihood that one of the implementations will be more easily grasped by most of the groups.
The point I am trying to make is that 'readability' and 'maintainability' are not merely preferences - and they can be measured.
However, they often appear to be just preferences, as a significant number of people seem to mask their own personal preferences behind these two terms.
One must walk a fine line between idealism and recognizing that perfection is practically impossible to achieve: on the one hand, without some sort of ideals to strive toward, no major improvements or paradigm-shifting developments will be made; on the other, getting bogged down in minutiae in a quest to perfectly embody a Platonic form is suicidal.
I've literally never had to make tradeoffs.
I work for the government, and we never have deadlines tho lmao.
We can just polish the project for however long we want.
Can it (readability and maintainability) only mean having some rules that the team has agreed upon? Like linting preferences or something that makes code more familiar when you're doing a code review of a junior dev.
Using consistent tabs for example makes blocks clear with your favorite indentation size, and blocks dumb terminals from running pasted lines.
The question should be "how much mental bandwidth would be required to follow what this piece of code is doing?" And you won't believe how big a difference descriptive variable names and function names make.