9 ms·

What does code readability mean? (2018)

58 points by signa11 6y ago

nendroid 6y ago
>By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov difficult and challenging, but we don’t say “Macbeth is unreadable.” We understand that the problem lies with the reader. Why does the responsibility Have to be solely on the reader? There's plenty of code out there that's unreadable because of the coder, how is this outside of the realm of possibility? Why is all the onus and bias on the reader? For example, readable: measurementOfLeftBottomSideOfBox = 200; versus unreadable (an acronym of Left Bottom Side): LBB = 200; Just like English, programming languages rely on the talent writer and on the abilities of the reader At the same Time. The best code is code written by a talented programmer who can make the code readable to All people of All skill levels. One thing people get confused about is readability and elegance. Obviously "measurementOfLeftBottomSideOfBox" is readable but not elegant. While "LBB" is certainly elegant but not readable. My philosophy is readability over elegance, but you will find many programmers are unaware of this dichotomy and have a strict subconscious aversion to writing something ugly like "measurementOfLeftBottomSideOfBox." This aversion leads to more unreadability than necessary. It's some subconscious thing in our minds that makes us code this way but when you think about it.... there's no logical point in it at all. Aim to encode as much context as possible into your code because it's completely irrelevant how ugly the variable appears.
- alfonsodev 6y ago
  but wouldn't be 'measurementOfLeftBottomSideOfBox' a smell, of data being too flat ? box.measures.sides['left-bootom'] vs measurementOfLeftBottomSideOfBox I know your point is elegant vs readable which I agree I just want to note another dimension that could be flat vs well structured data.
  - nendroid 6y ago
    What's wrong with flat data? Why is nested data better than flat data? If you think about it, there's really nothing wrong with either. The only reason you would want to structure your data like that is if you want to think about the Box as a whole from a more abstract level. But there's nothing wrong with writing an entire app that focuses on the measurement of the left bottom side of a box. If that's the requirement, than there's no need to define the measurement as part of a higher order type "Box" if you're not doing anything with the other measurements.
    - alfonsodev 6y ago
      Nothing wrong perse, but talking about readability, we see the world in categories and we communicate abstractions in words, I didn't say flat data is wrong, but that word in particular being too long smells like a bit of structure is needed, just to add another dimension to consider, which is how we abstract things in the world and model them in software matters.
      - nendroid 6y ago
        But if the structure is unused and my program only deals with a single integer does it make sense to modify the structure of the program for readability? No. If my program only modifies the left bottom side of the box it doesn't need the whole box defined. In this case and many cases similar to this, it's totally fine encoding more verbosity into the naming of the integer. The "smell" your sensing here is only called a smell because you can't logically explain it. Your brain is firing off a false alarm. I can easily make a variable name that can trigger the false alarm but you won't be able to come up with a reasonable nested structure to contain it. theColorOfTheSkyOnAThursdayAt6PM = "ReddishOrange" What are you gonna do here? I have a string that represents a color of the sky at a certain day on a certain time. What structure can reasonably contain this concept and ONLY this concept. Unless you want to define a structure called Sky the long name is the only possibility.
        alfonsodev 6y ago
        Is all context, if you have such specific need probably the app context is already understood and there is no need to have such big names, perhaps the apps is called, 'colors of Thursday 6pm' the you just hold a variable for sky. Same for box side, if your app only deals with a side, then is boxSide, you wouldn't say upperBottleTap, because all bottles have the tap on the upper side, and there is only one, so context is everything.
- psychoslave 6y ago
  Well, BCC actually seems quite the total opposite of elegance, according to my own sense of elegance. Elegance is far more subjective. Take a panel of some equally experimented programmers, and ask them to assess some code on its readability and elegance. I would expect the latter to vary far more greatly. Thus said I would find the other example an ominous sign on the code architecture. I would be more at ease to find a line like : box.edge(3).span.set(200) Or any syntactic variation of such statement. It's not the variable name per se, it's what it conveys about the abstractions used in the code base.
  - nendroid 6y ago
    >Thus said I would find the other example an ominous sign on the code architecture. I would be more at ease to find a line like : That's just your bias kicking in. I didn't define the requirements of the program. If I defined the requirements of the program to be ONLY printing out a number that represents the left edge of a box when the measurement is inputted into the console than defining an entire box struct is in itself a code "architecture" problem. Maybe another name wouldn't trigger any "Smell". speedOfLightInVacuumMetersPerSecond = 99999999999.... Is your brain telling you that it should be structured like so:? Vacuum.light.speed = 9999999999 Likely no, because it doesn't make sense to place light as a parameter of vacuum... showing that a big long phrase in a variable name is not in itself a "smell" that needs to be "re architected." You see it is not the grammar of the phrase that is making you want to restructure the code but the contextual meaning. This is one of those optical illusion like triggers in our brain, you want to organize something in a certain way but my post didn't give you a logical reason to do so. I never defined that an entire Box was provided as input.
    - psychoslave 6y ago
      Of course, context modulates everything. Here the context is an informal discussion to throw generalities on our own feelings on what makes a code readable. Sure, for more specific cases backed with some contextual data, it might be overkill to have a too sophisticated code hierarchy. For your new example, I would find any of the following more fine: maximum_celerity = 300 # Mm/s class Physics { public const speed c = 299792458; } current_pace = speed(particle: photon, environment: vacuum, unit: Units.parsecs_per_year) So, I agree, length of identifiers alone is not enough to trigger a "this would be more nicely structured as…", and context matter. "speedOfLightInVacuumMetersPerSecond" is readable, and might be good enough for some specific contexts. But I wouldn’t take that as a desirable practice example. Just because context matters, doesn’t mean that "all generality are absolute evil" (a statement that condemn itself).
- valenterry 6y ago
  > The best code is code written by a talented programmer who can make the code readable to All people of All skill levels. Unfortunately this is not true. Code is like language. You can make it readable for everyone by using the most easy to comprehend and least ambiguous language. But doing so decreases efficiency for both "advanced" writers and readers. "Advanced" grammar and vocabulary exists for a reason - it allows to express thoughts more succinct and concise and can decrease the time to understand something in great level of detail and context by magnitudes. But it requires knowledge and shared context between writer and reader. It's the same for using a very efficient compression algorithm vs. plaintext. You cannot have the advantages of both at the same time. Pick your poison. (I assume you understand "pick your poison", a non-native reader might not. It's so nice and concise, isn't it? :)
  - moonchild 6y ago
    As another example, consider the simple wikipedia[1]. It undeniably serves a very important role. Would it be appropriate for it to replace the standard english wikipedia? Or, would it be appropriate for all scientific literature to be written in the style of simple wikipedia? Simplicity and accessibility are undeniably important. But they shouldn't be your only goals. 1. https://simple.wikipedia.org/wiki/Main_Page https://simple.wikipedia.org/wiki/Main_Page
  - nendroid 6y ago
    Unfortunately for your argument, it actually is completely true. You're thinking about it the wrong way, an analogy to english doesn't prove your point when the analogy is irrelevant. Sure there's advanced vocabulary in English. But within that domain the english is still understandable. If the reader understands the domain he understands what is written and does not need to decipher or decode what is written. The domain expert just reads it and gets it, no deciphering needed. This is not what happens with domain specific code and this is not how domain experts read code therefore your analogy does not apply. Reading code tends to be very very different from reading english and much much slower. Reading is actually an inaccurate term. The reader for code spends much of his time deciphering code and any name that helps elucidate context and eliminate deciphering is a plus. This occurs EVEN for domain specific code. What happens with domain specific code is that a programmer tends to make up abbreviations on the fly and ends up writing something that is not readable at first glance and the reader needs to decipher the code. For example let's say I'm a domain expert in robotics and I want to encode positioning of the robot. For elegance I use this: xPosRelB = 23 which is short for x position relative to base. versus meters_west_from_base = 23 I can assure you 95% of programmers write the former rather than the latter and it's definitely not for efficiency gains. You might lose like 1 nanosecond of efficiency reading the latter but this only applies if you already know the meaning of xPosRelB, seriously if every single variable was written in the same way as the former you LOSE efficiency from trying to decipher meaning from context. The end result is that in order to figure out what xPosRelB is the reader always has to sort of dig a bit at the context. He has to see how it's used, where that variable comes from or in other words he needs to "decipher" it. This is super common in programming but not very common when reading English. Again your analogy does not apply. In short the second name in the example is just read and understood and is by far the better choice. When you ask the average programmer why he wrote xPosRelB rather than meters_west_from_base, he'll tell you that meters_from_base is too long and too ugly. Programmers bitch and moan about stuff like this that doesn't even matter. I had one guy tell me that you shouldn't mix and match camel_case or snakeCase because it just looks bad (there's a real reason why people don't mix it, and it's not aesthetics). If I go meta and bring this topic up and ask the programmer why again.... then he brings up reading efficiency, exactly what you're doing here. Readability and structure is what's important not aesthetics. What matters is that someone can read your code rather than decipher it. Length and prettiness contribute nothing to readability and barely dents reading efficiency. Domain targeted programming is stuff like this: gallonsOfCompoundV = 34 Compound V is the domain. There's no need to explain what compound V is in the variable name. This is not a big problem with coding for readability. The big problem and the problem I am addressing is this: compVg = 34 Seriously. Someone once complained to me about the word "Of" in my variable name. My bad, I'm sorry that added 2 nanoseconds to your reading time with the word "of". Of course the team may have conventions. For example my team prefixes the letter k to all constants. This stuff is fine and doesn't harm readability, but this is not what I'm talking about.
- userbinator 6y ago
  I can just as well argue that long rambling variable names are unreadable, because they obscure the macro-level structure of the code and the continuous repetition creates extra cognitive load ("is this really the same variable as the other one? It looks like the first three words are the same, but...") especially when one tries to keep track of several of these huge names and follow the dataflow. Also, left and bottom together refers to a point, not a side; so I would be doubly perplexed upon encountering such a name.
  - nendroid 6y ago
    >I can just as well argue that long rambling variable names are unreadable, because they obscure the macro-level structure of the code and the continuous repetition creates extra cognitive load ("is this really the same variable as the other one? It looks like the first three words are the same, but...") especially when one tries to keep track of several of these huge names and follow the dataflow. This problem you describe occurs in the english language. In formal documentation of code written in English tends to be by far more verbose in their explanation of code than the code itself. Yet we don't complain about english? Why? What if I take all the crazy shortcuts we use in programming names and use that in documentation and daily communication. Would it make my communication seem less like rambling and seem more clear? Would it help lessen the obscurity of the macro level structure of my point? Will removing the continuous use of grammatical repetition with words like "the" or "and" lessen the large cognitive load on your brain so you can understand my english? No it likely won't. In fact it will make me LESS understandable. The dichotomy here illustrates a bias within human nature. For some reason people perceive a certain level of verbosity in code to be bad but not so in english. Given the fact that even among programmers English is much more readable than code I would say that there is definitely a huge unrealized mass delusion going on here. Have you heard of literate programming by donald knuth? It's literally about taking every line of code and upping the verbosity by 10x by replacing it with a macro of an english paragraph. Literally an extreme version of the verbose variable naming I'm describing. If you can see validity in literate programming than basically my variable naming is a tiny tiny step in that direction.
    - valenterry 6y ago
- ZephyrBlu 6y ago
  > My philosophy is readability over elegance, but you will find many programmers are unaware of this dichotomy and have a strict subconscious aversion to writing something ugly like "measurementOfLeftBottomSideOfBox." I strongly believe that naming like "measurementOfLeftBottomSideOfBox" is not that helpful or readable. A name like that implies that there are measurements for each side of this box, so following that naming scheme we would have at least: measurementOfLeftBottomSideOfBox measurementOfRightBottomSideOfBox measurementOfLeftTopSideOfBox measurementOfRightTopSideOfBox Look at how many much useless text we have here. "measurementOf" and "SideOfBox" add nothing but clutter to the naming, and writing out practically the same thing 4 times suggests we could abstract this into a data structure. I know I'm being overly pedantic in this case, but I think the sentiment behind this type of naming commits a few sins: 1) It's overly verbose. More than 3 words is a warning sign to me. 2) It's specific rather than generic. For instance if I name a function "sortSheepByHoofSize", it implies the reader know what hoofs are, cares about them and knows how to measure them. Whereas when naming it "sortSheep" or perhaps even just "sort", it's immediately understandable on a surface level to practically everyone. 3) Following on from 2), this type of naming lacks context. We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. Oftentimes there's repeated information in names that could be inferred from context instead.
  - nendroid 6y ago
    >Look at how many much useless text we have here. "measurementOf" and "SideOfBox" add nothing but clutter to the naming, and writing out practically the same thing 4 times suggests we could abstract this into a data structure. First off this "clutter" exists in the English language itself yet I hear no one complaining. I don't communicate with other people using shortcuts and context aware abbreviations like your suggesting. I literally say "here are the measurements of the box" both in written documentation and by sound, what black magic says that this is so wrong to do in code? Anyway here it is: struct measurementsOfBox = { measurementOfLeftBottomSideOfBox measurementOfRightBottomSideOfBox measurementOfLeftTopSideOfBox measurementOfRightTopSideOfBox } There is Nothing wrong with above code. Clutter doesn't harm readability it just harms aesthetics. And useless? Are you sure? Even if it was useless what harm does it do? Now you could argue that the clutter itself can hurt reading efficiency. But honestly think about it. That's like 5 seconds of extra reading out of your life. It's not a big deal. Most programmers just have this version of OCD. I get it the struct looks really ugly, but there is nothing logically wrong with it. I mean you could make it more elegant like this: struct Box { x y z t } But this could lead to all kinds of other issues. For example because I didn't label anything with "measurement" now the reader can mistake the values for the "positioning" of the box as opposed to "measurements" of the box. You made a common mistake here in your naming in assuming that "measurement" was a useless prefix. It's not... but that's besides the point because every program writer can make that mistake. That's why when you add a bit more clarity to your naming you have a larger chance to avoid this mistake at a small cost of adding some ugliness to your code. >1) It's overly verbose. More than 3 words is a warning sign to me. Warning sign of what? It's a similar warning sign that your brain fires off when you're alone in the dark in the woods. There's nothing to fear logically but your brain kicks off warnings regardless. Same with this, your brain kicks off some sort of warning but when you work it out logically there's Nothing. Verbose code is not bad just like verbose documentation is not bad. >2) It's specific rather than generic. For instance if I name a function "sortSheepByHoofSize", it implies the reader know what hoofs are, cares about them and knows how to measure them. Whereas when naming it "sortSheep" or perhaps even just "sort", it's immediately understandable on a surface level to practically everyone. Data referring to a specific concept or a generic concept is a structural decision made by you. I chose data referring to a specific concept. This happens in code. Not everything is generic and for specific things there's nothing wrong with using very specific names. >3) Following on from 2), this type of naming lacks context. We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. Oftentimes there's repeated information in names that could be inferred from context instead. >>We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. There's no downside into packing more info into a name. Sure it can get to a point where it's unreasonable but in general there's nothing wrong with me calling something a measurement when that's what it is... This is an aesthetic issue that programmers react due to human bias, but there's nothing intrinsically wrong with prefixing measurement onto box. There's nothing wrong with repeated information either. By prefixing measurement onto the Box struct I let everyone know that these are measurements on the box and not the position of the box. It's ugly but ugliness has nothing to do with readability or structure. This is the bias programmers need to get rid of. Find beauty in the structure of your code and find readability in the naming. Don't make the mistake of trying to find beauty in naming. Nobody wants to decipher code with poetic naming. Have you guys heard of literate programming by donald knuth? He's taking what I'm talking about to extreme heights.
- bluGill 6y ago
  Change english to Korean and all the variables names to the Korean translation and read your reply again. To someone who is fluent in Korean there is no problem, but to the rest of us English speakers (who don't know Korean) the long names with weird symbols are even less readable than lbb. I have in my day job some code we got from Korea. I'm told by those who have spent the time to understand it that it is good code. But since it was written in Korean it is a level harder to figure out.
  - nendroid 6y ago
    I use the word "english" but really my argument is language agnostic. Choose the language relative to the audience is my moto. >I have in my day job some code we got from Korea. I'm told by those who have spent the time to understand it that it is good code. But since it was written in Korean it is a level harder to figure out. Exactly this is my point. Abbreviations, lack of verbosity in naming and shortcuts might as well be Korean for the reader. It really doesn't matter how good the code is.... the understandability of your naming is by far more important. Totally agreed.
CobrastanJorji 6y ago
> Should we strive to satisfy the Shakespeare for Dummies demographic? A thousand times, yes! There is code out there so elegant and pure that, after painstakingly pulling apart its pieces and analyzing each choice of word like a Robert Frost poem, we're left feeling like we've seen a face of God. When debugging in the middle of the night because an alarm went off or a customer is angry, T. S. Elliot is absolutely the last thing I want to see. When I want to maintain a large system quickly, I want to be treated like I'm 5. I don't want Shakespeare. I don't even want Shakespeare for Dummies. I want "Dick and Jane Process a Customer Order." I absolutely agree with the author that when I say "This code is unreadable," I actually mean "I haven’t spent enough time trying to read," but time is something I don't have. My coworkers and I will likely read the same code many times. We only have so much time to spend reading code. Code that takes a lot of time to read is bad. We do not have time to keep studying the code until it is no longer unreadable. We are more than willing to invest quite a lot of additional time writing the code to make the time it takes to read the code as low as conceivably possible. Heck, with a small handful of exceptions, I will happily trade quite a bit of performance for simplicity. Sure, if you're Terje Mathisen, and you're writing Quake 3, and Polyhymnia or Velvel Kahan descend from Mt. Helicon singing of inverse square roots and the number 0x5f3759df, and you happen to be trying to optimize a 3D game engine, sure, write poetry. Ages and ages hence, we shall read of your algorithm by the fireside and slowly smile as a blog explains to us why it is brilliant. Sing on! But if you're writing a normal program that's gonna be maintained frequently by normal people, you call security. That muse does not have a badge. She does not work here. There is a clear "no children of Mnemosyne" sign in the lobby.
- z3t4 6y ago
  Also you should not need to press "go to definition" 10 times in a row...
- trentnix 6y ago
  Preach it. The less cognitive load required to dive in and make changes, the better. The young version of me wanted every opportunity to show off, but the grizzled veteran I am today is in love with simplicity and clarity.
null_object 6y ago
I’m sure I recall seeing a graph showing the development of a programmer over time, showing how their code starts out as simple but scarcely readable, gradually gets better but then descends for a period into excessive abstraction and unreadability as they learn new and exciting aspects of the language and can’t resist the temptation to show-off this abstruse knowledge. Before climbing back into simple elegance and understandability as their self-confidence and assurance in the language gradually subsumes the need to be ‘clever’ and gnostic in their coding. I’m amused the author chose Shakespeare as an example of ‘difficult’ writing. Shakespeare is eminently readable at all levels: his skill was precisely that his compelling stories can be read for their exciting narrative by anyone, and equally can be mined for deeper meaning by those that are interested in unraveling his layers of metaphor and symbolism.
- goto11 6y ago
  Shakespeare is difficult to read because many words have changed meaning over time. So unless you are very careful when reading, you will think you understand, but actually misunderstand a lot. Some of the puns does not even make sense anymore because the pronunciation have changed. You basically have to be a specialized linguist to understand them all.
  - sbelskie 6y ago
    I wouldn’t recommend anyone read a non-annotated version of Shakespeare.
  - DanBC 6y ago
    Yes. Here's another example about hats where the meaning is mostly hidden. https://www.bbc.co.uk/programmes/articles/cZHd4yrC7DV2sdyndn372K/transcript-shakespeares-restless-world-programme-8 https://www.bbc.co.uk/programmes/articles/cZHd4yrC7DV2sdyndn...
fsnowdin 6y ago
I just finished a re-factoring project recently. This article really made me re-think everything I did.
TeMPOraL 6y ago
> When we observe this tendency in other (non-programming) contexts we may interpret it as laziness or short attention span. When we react this way to code we blame the code and the original programmer. Strongly agreed. Particularly about a lot of examples of the so-called "clever code". Programming is a profession. You can't expect to forever coast on what little knowledge landed you your first job. You're supposed to learn and improve over time. That means learning to understand more complex code, architectures and programming paradigms. I can't read Haskell code at all. But I don't claim it's "clever" or "unreadable". I realize the code is probably fine, it's me who needs to pick up a book and learn the language. There's rampant anti-intellectualism and (the bad kind of) laziness in programmer circles, thinly veiled as concern for efficiency ("less clever code = easier to debug", or "helps juniors contribute", as if the job of a junior wasn't - in big part - to be learning to become a senior); I find it just being penny wise, pound foolish. Lambda expressions[0], regular expressions, pattern matching, Lisp macros - this is not clever code, these are tools that can greatly reduce complexity and improve readability. They just require spending a few hours or days with a book, every now and then. -- [0] - Yes, really; few jobs back, just after we transitioned to Java 8, I was told by my boss to maybe refrain from using lambda expressions for the sake of "more junior" people. Right, because polluting code with anonymous classes is easier on juniors than (event) -> { few lines; } in some GUI event handler.
aceBacker 6y ago
I think the point is that we develop in a stream of consciousness. We figure out what we need, pull it in, do what we need to do as it pops into our thoughts. When we're done it's time to start writing. Take that stream of consciousness and make it more logical. Easier to follow. Refined. That's how authors write books. No one writes a first draft and declared the book finished. Every creative effort requires iteration to improve.
m_mueller 6y ago
I’m missing a bit of prescriptiveness here. Here’s a formula I’ve arrived at after 15y of academic and professional programming - sharing here with the purpose of having it challenged by the reader: * every abstraction has a cost - DO a quick cost/benefit analysis in your head, or even better in the code comments, when choosing for/against an abstraction. * generally, start with KISS. - a process begins with a verb and its design usually starts with being a function/procedure - pieces of data that belong together across multiple processes should start out as an immutable object or struct. In python I’m almost never using direct descendants of object, rather I inherit either from NamedTuple (for final classes) or I decorate with @dataclass(frozen=True) for non-final. * using the above, you’ll start seeing violations of DRY. DO use the rule-of-threes. If there’s a second repetition you’re either writing, or already anticipate based on the JIRA backlog - factor out the repeating code using an appropriate abstraction. I’ve found that code written with these rules tends to be simple yet clean (these two properties can often be opposite, I’ve seen simple code that is constantly repeating itself and thus becomes unmaintainable, and I’ve also seen clean code that is the opposite of simple because of an abundance of abstractions (think FizzBuzzEnterprise).
- slx26 6y ago
  Yes, abstractions make symbolic sense for humans, but in a technical context they are most often problematic, because intuition and technical correctness rarely align. Not like they are on opposite sides, but intuition almost always has a lot of technical holes, and when you are coding, something always ends up surfacing from those holes... and it's never pleasant. In this sense, focusing on the data and simple rules is most likely to bring us closer to the true technical problem that we are trying to solve. Abstractions and organization and good names are still vital because we do need an intuitive vision of the system as a whole, but the technical processes need to be strictly correct, not just intuitive.
- fsnowdin 6y ago
  That FizzBuzzEnterprise thing is hilarious. I can't believe I didn't know about it until now.
azaza123 6y ago
The problem of the article is the same as the problem of the general discussion on how to program better: quality of arguments. Instead of conducting scientific studies on code readability, programmers keep on sharing their opinions which they support with anecdotes or citations of Shakespeare. There is so much for the community to learn about...
- aszen 6y ago
  I think the whole point of the article was that code readability is not a scientific phenomenon you can measure by conducting studies. How readable the code is, depends on who's reading, what's their background and what style do they prefer for expressing logic.
aszen 6y ago
Code readability is just one of the goals we aim for while designing software, performance is another, stability is another, flexibility and ability to make changes is yet another. While reading any code I tend to think about these tradeoffs and see if that hard to read code is actually hard for a reason or simply a mess because no one took care of it. Writing dumb easy looking duplicate code is not optimal either, I don't see an issue with stable, fast and efficient code that's harder to understand yet works brilliantly. One can easily increase readability of such code by adding comments but one can't get performance, stability and flexibility by writing comments. Optimising for dummies just because code is easier to debug isn't a good idea, often times I have to debug easy looking code only to find that it's not that easy in execution as it was in reading. Simple code often doesn't handle all the edge cases, abstraction less code is harder to maintain and change, easy code can't evolve and grow with business needs. It's only when code is unreadable, buggy and slow that it starts to become a real mess. Also a shout out to Rich Hickey's distinction between easy and simple, creating simple code requires a lot more effort and thought and is not easy to just read and modify by dummies.
- kungtotte 6y ago
  I think a lot of the time people think they have performance issues when they in fact don't, likewise with stability and flexibility. In most cases, writing the readable and straightforward version first and only moving to the less readable but more X version (for any given value of X) after it's evident that you need to is the optimal solution. It's the programming equivalent to buying cheap tools first and only buying the expensive version once the cheap one breaks: If it breaks you used it enough to warrant the expensive and more durable one, and if it didn't break you didn't have to spend more money than necessary.
  - aszen 6y ago
    I do see your point but let me say a bit about performance, performance matters a whole lot if your software is being used seriously all day long for getting things done in the real world. If your software is going to be someone's day job it can't afford to be slow because users would take note and complain loud and clear because it's wasting their time. Just imagine git taking 15mins for showing diffs, would you accept that for an improvement in code readability and straightforwardness. So for different industries there are different X's that matter a whole lot more than mere readability and developer convenience.
deleted 6y ago
[deleted]
29athrowaway 6y ago
This does not acknowledge that code styles can be compared in objective ways. What is more readable? # Expression 1 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 # Expression 2 10 One requires to do 9 arithmetic operations in your head, perhaps more than once if you lost count, the other one doesn't. You can compare code in terms of length, nesting, cyclomatic complexity, number of negations, number of inputs, etc. It's not just subjective bikeshedding.
- bluGill 6y ago
  1 is simpler in most cases because I trust the computer to get the answer, but I need to know all the explicit parts. 2 hides where it all came from for an answer which might be wrong.
  - 29athrowaway 6y ago
    Usually you give each constant a name and then operate on them symbolically. If it's a simple enough operation you can skip that and just add a comment. In this example, there are 9 arithmetic operations and there are clearly more readable ways of doing this. This is the point I am trying to make. For the author of this article, using roman numerals and using arabic numerals are the same because they represent the same quantities. However, in practice, if you have 2 accountants and tell one of them to use roman numerals, the one using roman numerals will be less productive, make more mistakes and will likely be frustrated.
  - luckylion 6y ago
    I agree very much. 60 * 60 * 24 * 3 vs 258200. Which one is the number of seconds in three days?
- goto11 6y ago
  What is the code intended to communicate? It we don't know the intention we cant say which example most clearly communicates this intention.
diegolo 6y ago
there is this quote from Clean Code by uncle Bob that I simply love. 'Avoid mental mapping: In general programmers are pretty smart people. Smart people sometimes like to show off their smarts by demonstrating their mental juggling abilities. After all, if you can reliably remember that r is the lower-cased version of the url with the host and scheme removed, then you must clearly be very smart.'
virgilp 6y ago
> “Good code is simple” doesn’t actually say anything. This is why I love Rich Hickey's "simple made easy" talk, because with it you an make the distinction between "simple" and "easy". "Good code is simple" absolutely says something and has an objective meaning, at least for some people.
jondubois 6y ago
The most important characteristics are: - Components have clear separation of concerns and well encapsulated state. (Should be easy to explain what a component does to a non-technical person). - Names of components are clear and rooted in the business domain; not made up abstract technical concepts. This relates to the first point. - Simple interfaces between components (components interact with each other through a simple, plain language; avoid passing complex instances to each other). Simple function arguments like strings, numbers and other simple pass-by-value structures are ideal. Components should be able to invoke actions on other components but the responsibility of how this is achieved lies entirely with the component who is responsible for that concern; this is also why state encapsulation is important. - Clear unidirectional data flows throughout the system. State changes for a particular kind of state should originate from a single place in the code. If you notice, all of these characteristics work together and build on top of each other. It's all or nothing. You either get all of these right or none of these right.
chrisma0 6y ago
There is a recent study (to be published at ESEM'20) on an empirical validation of "Cognitive Complexity" as a measure of source code understandability: https://arxiv.org/abs/2007.12520 https://arxiv.org/abs/2007.12520 The authors state in the conclusion: "The metric correlates with the time it takes a developer to understand source code, with a combination of time and correctness, and with subjective ratings of understandability."

58 points by signa11 6y ago

>By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov difficult and challenging, but we don’t say “Macbeth is unreadable.” We understand that the problem lies with the reader. Why does the responsibility Have to be solely on the reader? There's plenty of code out there that's unreadable because of the coder, how is this outside of the realm of possibility? Why is all the onus and bias on the reader? For example, readable: measurementOfLeftBottomSideOfBox = 200; versus unreadable (an acronym of Left Bottom Side): LBB = 200; Just like English, programming languages rely on the talent writer and on the abilities of the reader At the same Time. The best code is code written by a talented programmer who can make the code readable to All people of All skill levels. One thing people get confused about is readability and elegance. Obviously "measurementOfLeftBottomSideOfBox" is readable but not elegant. While "LBB" is certainly elegant but not readable. My philosophy is readability over elegance, but you will find many programmers are unaware of this dichotomy and have a strict subconscious aversion to writing something ugly like "measurementOfLeftBottomSideOfBox." This aversion leads to more unreadability than necessary. It's some subconscious thing in our minds that makes us code this way but when you think about it.... there's no logical point in it at all. Aim to encode as much context as possible into your code because it's completely irrelevant how ugly the variable appears.

alfonsodev 6y ago
but wouldn't be 'measurementOfLeftBottomSideOfBox' a smell, of data being too flat ? box.measures.sides['left-bootom'] vs measurementOfLeftBottomSideOfBox I know your point is elegant vs readable which I agree I just want to note another dimension that could be flat vs well structured data.
- nendroid 6y ago
  What's wrong with flat data? Why is nested data better than flat data? If you think about it, there's really nothing wrong with either. The only reason you would want to structure your data like that is if you want to think about the Box as a whole from a more abstract level. But there's nothing wrong with writing an entire app that focuses on the measurement of the left bottom side of a box. If that's the requirement, than there's no need to define the measurement as part of a higher order type "Box" if you're not doing anything with the other measurements.
  - alfonsodev 6y ago
    Nothing wrong perse, but talking about readability, we see the world in categories and we communicate abstractions in words, I didn't say flat data is wrong, but that word in particular being too long smells like a bit of structure is needed, just to add another dimension to consider, which is how we abstract things in the world and model them in software matters.
    - nendroid 6y ago
      But if the structure is unused and my program only deals with a single integer does it make sense to modify the structure of the program for readability? No. If my program only modifies the left bottom side of the box it doesn't need the whole box defined. In this case and many cases similar to this, it's totally fine encoding more verbosity into the naming of the integer. The "smell" your sensing here is only called a smell because you can't logically explain it. Your brain is firing off a false alarm. I can easily make a variable name that can trigger the false alarm but you won't be able to come up with a reasonable nested structure to contain it. theColorOfTheSkyOnAThursdayAt6PM = "ReddishOrange" What are you gonna do here? I have a string that represents a color of the sky at a certain day on a certain time. What structure can reasonably contain this concept and ONLY this concept. Unless you want to define a structure called Sky the long name is the only possibility.
      - alfonsodev 6y ago
        Is all context, if you have such specific need probably the app context is already understood and there is no need to have such big names, perhaps the apps is called, 'colors of Thursday 6pm' the you just hold a variable for sky. Same for box side, if your app only deals with a side, then is boxSide, you wouldn't say upperBottleTap, because all bottles have the tap on the upper side, and there is only one, so context is everything.
psychoslave 6y ago
Well, BCC actually seems quite the total opposite of elegance, according to my own sense of elegance. Elegance is far more subjective. Take a panel of some equally experimented programmers, and ask them to assess some code on its readability and elegance. I would expect the latter to vary far more greatly. Thus said I would find the other example an ominous sign on the code architecture. I would be more at ease to find a line like : box.edge(3).span.set(200) Or any syntactic variation of such statement. It's not the variable name per se, it's what it conveys about the abstractions used in the code base.
- nendroid 6y ago
  >Thus said I would find the other example an ominous sign on the code architecture. I would be more at ease to find a line like : That's just your bias kicking in. I didn't define the requirements of the program. If I defined the requirements of the program to be ONLY printing out a number that represents the left edge of a box when the measurement is inputted into the console than defining an entire box struct is in itself a code "architecture" problem. Maybe another name wouldn't trigger any "Smell". speedOfLightInVacuumMetersPerSecond = 99999999999.... Is your brain telling you that it should be structured like so:? Vacuum.light.speed = 9999999999 Likely no, because it doesn't make sense to place light as a parameter of vacuum... showing that a big long phrase in a variable name is not in itself a "smell" that needs to be "re architected." You see it is not the grammar of the phrase that is making you want to restructure the code but the contextual meaning. This is one of those optical illusion like triggers in our brain, you want to organize something in a certain way but my post didn't give you a logical reason to do so. I never defined that an entire Box was provided as input.
  - psychoslave 6y ago
    Of course, context modulates everything. Here the context is an informal discussion to throw generalities on our own feelings on what makes a code readable. Sure, for more specific cases backed with some contextual data, it might be overkill to have a too sophisticated code hierarchy. For your new example, I would find any of the following more fine: maximum_celerity = 300 # Mm/s class Physics { public const speed c = 299792458; } current_pace = speed(particle: photon, environment: vacuum, unit: Units.parsecs_per_year) So, I agree, length of identifiers alone is not enough to trigger a "this would be more nicely structured as…", and context matter. "speedOfLightInVacuumMetersPerSecond" is readable, and might be good enough for some specific contexts. But I wouldn’t take that as a desirable practice example. Just because context matters, doesn’t mean that "all generality are absolute evil" (a statement that condemn itself).
valenterry 6y ago
> The best code is code written by a talented programmer who can make the code readable to All people of All skill levels. Unfortunately this is not true. Code is like language. You can make it readable for everyone by using the most easy to comprehend and least ambiguous language. But doing so decreases efficiency for both "advanced" writers and readers. "Advanced" grammar and vocabulary exists for a reason - it allows to express thoughts more succinct and concise and can decrease the time to understand something in great level of detail and context by magnitudes. But it requires knowledge and shared context between writer and reader. It's the same for using a very efficient compression algorithm vs. plaintext. You cannot have the advantages of both at the same time. Pick your poison. (I assume you understand "pick your poison", a non-native reader might not. It's so nice and concise, isn't it? :)
- moonchild 6y ago
  As another example, consider the simple wikipedia[1]. It undeniably serves a very important role. Would it be appropriate for it to replace the standard english wikipedia? Or, would it be appropriate for all scientific literature to be written in the style of simple wikipedia? Simplicity and accessibility are undeniably important. But they shouldn't be your only goals. 1. https://simple.wikipedia.org/wiki/Main_Page https://simple.wikipedia.org/wiki/Main_Page
- nendroid 6y ago
  Unfortunately for your argument, it actually is completely true. You're thinking about it the wrong way, an analogy to english doesn't prove your point when the analogy is irrelevant. Sure there's advanced vocabulary in English. But within that domain the english is still understandable. If the reader understands the domain he understands what is written and does not need to decipher or decode what is written. The domain expert just reads it and gets it, no deciphering needed. This is not what happens with domain specific code and this is not how domain experts read code therefore your analogy does not apply. Reading code tends to be very very different from reading english and much much slower. Reading is actually an inaccurate term. The reader for code spends much of his time deciphering code and any name that helps elucidate context and eliminate deciphering is a plus. This occurs EVEN for domain specific code. What happens with domain specific code is that a programmer tends to make up abbreviations on the fly and ends up writing something that is not readable at first glance and the reader needs to decipher the code. For example let's say I'm a domain expert in robotics and I want to encode positioning of the robot. For elegance I use this: xPosRelB = 23 which is short for x position relative to base. versus meters_west_from_base = 23 I can assure you 95% of programmers write the former rather than the latter and it's definitely not for efficiency gains. You might lose like 1 nanosecond of efficiency reading the latter but this only applies if you already know the meaning of xPosRelB, seriously if every single variable was written in the same way as the former you LOSE efficiency from trying to decipher meaning from context. The end result is that in order to figure out what xPosRelB is the reader always has to sort of dig a bit at the context. He has to see how it's used, where that variable comes from or in other words he needs to "decipher" it. This is super common in programming but not very common when reading English. Again your analogy does not apply. In short the second name in the example is just read and understood and is by far the better choice. When you ask the average programmer why he wrote xPosRelB rather than meters_west_from_base, he'll tell you that meters_from_base is too long and too ugly. Programmers bitch and moan about stuff like this that doesn't even matter. I had one guy tell me that you shouldn't mix and match camel_case or snakeCase because it just looks bad (there's a real reason why people don't mix it, and it's not aesthetics). If I go meta and bring this topic up and ask the programmer why again.... then he brings up reading efficiency, exactly what you're doing here. Readability and structure is what's important not aesthetics. What matters is that someone can read your code rather than decipher it. Length and prettiness contribute nothing to readability and barely dents reading efficiency. Domain targeted programming is stuff like this: gallonsOfCompoundV = 34 Compound V is the domain. There's no need to explain what compound V is in the variable name. This is not a big problem with coding for readability. The big problem and the problem I am addressing is this: compVg = 34 Seriously. Someone once complained to me about the word "Of" in my variable name. My bad, I'm sorry that added 2 nanoseconds to your reading time with the word "of". Of course the team may have conventions. For example my team prefixes the letter k to all constants. This stuff is fine and doesn't harm readability, but this is not what I'm talking about.
userbinator 6y ago
I can just as well argue that long rambling variable names are unreadable, because they obscure the macro-level structure of the code and the continuous repetition creates extra cognitive load ("is this really the same variable as the other one? It looks like the first three words are the same, but...") especially when one tries to keep track of several of these huge names and follow the dataflow. Also, left and bottom together refers to a point, not a side; so I would be doubly perplexed upon encountering such a name.
- nendroid 6y ago
  >I can just as well argue that long rambling variable names are unreadable, because they obscure the macro-level structure of the code and the continuous repetition creates extra cognitive load ("is this really the same variable as the other one? It looks like the first three words are the same, but...") especially when one tries to keep track of several of these huge names and follow the dataflow. This problem you describe occurs in the english language. In formal documentation of code written in English tends to be by far more verbose in their explanation of code than the code itself. Yet we don't complain about english? Why? What if I take all the crazy shortcuts we use in programming names and use that in documentation and daily communication. Would it make my communication seem less like rambling and seem more clear? Would it help lessen the obscurity of the macro level structure of my point? Will removing the continuous use of grammatical repetition with words like "the" or "and" lessen the large cognitive load on your brain so you can understand my english? No it likely won't. In fact it will make me LESS understandable. The dichotomy here illustrates a bias within human nature. For some reason people perceive a certain level of verbosity in code to be bad but not so in english. Given the fact that even among programmers English is much more readable than code I would say that there is definitely a huge unrealized mass delusion going on here. Have you heard of literate programming by donald knuth? It's literally about taking every line of code and upping the verbosity by 10x by replacing it with a macro of an english paragraph. Literally an extreme version of the verbose variable naming I'm describing. If you can see validity in literate programming than basically my variable naming is a tiny tiny step in that direction.
  - valenterry 6y ago
ZephyrBlu 6y ago
> My philosophy is readability over elegance, but you will find many programmers are unaware of this dichotomy and have a strict subconscious aversion to writing something ugly like "measurementOfLeftBottomSideOfBox." I strongly believe that naming like "measurementOfLeftBottomSideOfBox" is not that helpful or readable. A name like that implies that there are measurements for each side of this box, so following that naming scheme we would have at least: measurementOfLeftBottomSideOfBox measurementOfRightBottomSideOfBox measurementOfLeftTopSideOfBox measurementOfRightTopSideOfBox Look at how many much useless text we have here. "measurementOf" and "SideOfBox" add nothing but clutter to the naming, and writing out practically the same thing 4 times suggests we could abstract this into a data structure. I know I'm being overly pedantic in this case, but I think the sentiment behind this type of naming commits a few sins: 1) It's overly verbose. More than 3 words is a warning sign to me. 2) It's specific rather than generic. For instance if I name a function "sortSheepByHoofSize", it implies the reader know what hoofs are, cares about them and knows how to measure them. Whereas when naming it "sortSheep" or perhaps even just "sort", it's immediately understandable on a surface level to practically everyone. 3) Following on from 2), this type of naming lacks context. We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. Oftentimes there's repeated information in names that could be inferred from context instead.
- nendroid 6y ago
  >Look at how many much useless text we have here. "measurementOf" and "SideOfBox" add nothing but clutter to the naming, and writing out practically the same thing 4 times suggests we could abstract this into a data structure. First off this "clutter" exists in the English language itself yet I hear no one complaining. I don't communicate with other people using shortcuts and context aware abbreviations like your suggesting. I literally say "here are the measurements of the box" both in written documentation and by sound, what black magic says that this is so wrong to do in code? Anyway here it is: struct measurementsOfBox = { measurementOfLeftBottomSideOfBox measurementOfRightBottomSideOfBox measurementOfLeftTopSideOfBox measurementOfRightTopSideOfBox } There is Nothing wrong with above code. Clutter doesn't harm readability it just harms aesthetics. And useless? Are you sure? Even if it was useless what harm does it do? Now you could argue that the clutter itself can hurt reading efficiency. But honestly think about it. That's like 5 seconds of extra reading out of your life. It's not a big deal. Most programmers just have this version of OCD. I get it the struct looks really ugly, but there is nothing logically wrong with it. I mean you could make it more elegant like this: struct Box { x y z t } But this could lead to all kinds of other issues. For example because I didn't label anything with "measurement" now the reader can mistake the values for the "positioning" of the box as opposed to "measurements" of the box. You made a common mistake here in your naming in assuming that "measurement" was a useless prefix. It's not... but that's besides the point because every program writer can make that mistake. That's why when you add a bit more clarity to your naming you have a larger chance to avoid this mistake at a small cost of adding some ugliness to your code. >1) It's overly verbose. More than 3 words is a warning sign to me. Warning sign of what? It's a similar warning sign that your brain fires off when you're alone in the dark in the woods. There's nothing to fear logically but your brain kicks off warnings regardless. Same with this, your brain kicks off some sort of warning but when you work it out logically there's Nothing. Verbose code is not bad just like verbose documentation is not bad. >2) It's specific rather than generic. For instance if I name a function "sortSheepByHoofSize", it implies the reader know what hoofs are, cares about them and knows how to measure them. Whereas when naming it "sortSheep" or perhaps even just "sort", it's immediately understandable on a surface level to practically everyone. Data referring to a specific concept or a generic concept is a structural decision made by you. I chose data referring to a specific concept. This happens in code. Not everything is generic and for specific things there's nothing wrong with using very specific names. >3) Following on from 2), this type of naming lacks context. We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. Oftentimes there's repeated information in names that could be inferred from context instead. >>We should leverage the context of surrounding code and abstractions to make naming understandable, instead of trying to pack all the meaning into one name. There's no downside into packing more info into a name. Sure it can get to a point where it's unreasonable but in general there's nothing wrong with me calling something a measurement when that's what it is... This is an aesthetic issue that programmers react due to human bias, but there's nothing intrinsically wrong with prefixing measurement onto box. There's nothing wrong with repeated information either. By prefixing measurement onto the Box struct I let everyone know that these are measurements on the box and not the position of the box. It's ugly but ugliness has nothing to do with readability or structure. This is the bias programmers need to get rid of. Find beauty in the structure of your code and find readability in the naming. Don't make the mistake of trying to find beauty in naming. Nobody wants to decipher code with poetic naming. Have you guys heard of literate programming by donald knuth? He's taking what I'm talking about to extreme heights.
bluGill 6y ago
Change english to Korean and all the variables names to the Korean translation and read your reply again. To someone who is fluent in Korean there is no problem, but to the rest of us English speakers (who don't know Korean) the long names with weird symbols are even less readable than lbb. I have in my day job some code we got from Korea. I'm told by those who have spent the time to understand it that it is good code. But since it was written in Korean it is a level harder to figure out.
- nendroid 6y ago
  I use the word "english" but really my argument is language agnostic. Choose the language relative to the audience is my moto. >I have in my day job some code we got from Korea. I'm told by those who have spent the time to understand it that it is good code. But since it was written in Korean it is a level harder to figure out. Exactly this is my point. Abbreviations, lack of verbosity in naming and shortcuts might as well be Korean for the reader. It really doesn't matter how good the code is.... the understandability of your naming is by far more important. Totally agreed.

CobrastanJorji 6y ago

> Should we strive to satisfy the Shakespeare for Dummies demographic? A thousand times, yes! There is code out there so elegant and pure that, after painstakingly pulling apart its pieces and analyzing each choice of word like a Robert Frost poem, we're left feeling like we've seen a face of God. When debugging in the middle of the night because an alarm went off or a customer is angry, T. S. Elliot is absolutely the last thing I want to see. When I want to maintain a large system quickly, I want to be treated like I'm 5. I don't want Shakespeare. I don't even want Shakespeare for Dummies. I want "Dick and Jane Process a Customer Order." I absolutely agree with the author that when I say "This code is unreadable," I actually mean "I haven’t spent enough time trying to read," but time is something I don't have. My coworkers and I will likely read the same code many times. We only have so much time to spend reading code. Code that takes a lot of time to read is bad. We do not have time to keep studying the code until it is no longer unreadable. We are more than willing to invest quite a lot of additional time writing the code to make the time it takes to read the code as low as conceivably possible. Heck, with a small handful of exceptions, I will happily trade quite a bit of performance for simplicity. Sure, if you're Terje Mathisen, and you're writing Quake 3, and Polyhymnia or Velvel Kahan descend from Mt. Helicon singing of inverse square roots and the number 0x5f3759df, and you happen to be trying to optimize a 3D game engine, sure, write poetry. Ages and ages hence, we shall read of your algorithm by the fireside and slowly smile as a blog explains to us why it is brilliant. Sing on! But if you're writing a normal program that's gonna be maintained frequently by normal people, you call security. That muse does not have a badge. She does not work here. There is a clear "no children of Mnemosyne" sign in the lobby.

z3t4 6y ago
Also you should not need to press "go to definition" 10 times in a row...
trentnix 6y ago
Preach it. The less cognitive load required to dive in and make changes, the better. The young version of me wanted every opportunity to show off, but the grizzled veteran I am today is in love with simplicity and clarity.

null_object 6y ago

I’m sure I recall seeing a graph showing the development of a programmer over time, showing how their code starts out as simple but scarcely readable, gradually gets better but then descends for a period into excessive abstraction and unreadability as they learn new and exciting aspects of the language and can’t resist the temptation to show-off this abstruse knowledge. Before climbing back into simple elegance and understandability as their self-confidence and assurance in the language gradually subsumes the need to be ‘clever’ and gnostic in their coding. I’m amused the author chose Shakespeare as an example of ‘difficult’ writing. Shakespeare is eminently readable at all levels: his skill was precisely that his compelling stories can be read for their exciting narrative by anyone, and equally can be mined for deeper meaning by those that are interested in unraveling his layers of metaphor and symbolism.

goto11 6y ago
Shakespeare is difficult to read because many words have changed meaning over time. So unless you are very careful when reading, you will think you understand, but actually misunderstand a lot. Some of the puns does not even make sense anymore because the pronunciation have changed. You basically have to be a specialized linguist to understand them all.
- sbelskie 6y ago
  I wouldn’t recommend anyone read a non-annotated version of Shakespeare.
- DanBC 6y ago
  Yes. Here's another example about hats where the meaning is mostly hidden. https://www.bbc.co.uk/programmes/articles/cZHd4yrC7DV2sdyndn372K/transcript-shakespeares-restless-world-programme-8 https://www.bbc.co.uk/programmes/articles/cZHd4yrC7DV2sdyndn...

fsnowdin 6y ago

I just finished a re-factoring project recently. This article really made me re-think everything I did.

TeMPOraL 6y ago

> When we observe this tendency in other (non-programming) contexts we may interpret it as laziness or short attention span. When we react this way to code we blame the code and the original programmer. Strongly agreed. Particularly about a lot of examples of the so-called "clever code". Programming is a profession. You can't expect to forever coast on what little knowledge landed you your first job. You're supposed to learn and improve over time. That means learning to understand more complex code, architectures and programming paradigms. I can't read Haskell code at all. But I don't claim it's "clever" or "unreadable". I realize the code is probably fine, it's me who needs to pick up a book and learn the language. There's rampant anti-intellectualism and (the bad kind of) laziness in programmer circles, thinly veiled as concern for efficiency ("less clever code = easier to debug", or "helps juniors contribute", as if the job of a junior wasn't - in big part - to be learning to become a senior); I find it just being penny wise, pound foolish. Lambda expressions[0], regular expressions, pattern matching, Lisp macros - this is not clever code, these are tools that can greatly reduce complexity and improve readability. They just require spending a few hours or days with a book, every now and then. -- [0] - Yes, really; few jobs back, just after we transitioned to Java 8, I was told by my boss to maybe refrain from using lambda expressions for the sake of "more junior" people. Right, because polluting code with anonymous classes is easier on juniors than (event) -> { few lines; } in some GUI event handler.

aceBacker 6y ago

I think the point is that we develop in a stream of consciousness. We figure out what we need, pull it in, do what we need to do as it pops into our thoughts. When we're done it's time to start writing. Take that stream of consciousness and make it more logical. Easier to follow. Refined. That's how authors write books. No one writes a first draft and declared the book finished. Every creative effort requires iteration to improve.

m_mueller 6y ago

I’m missing a bit of prescriptiveness here. Here’s a formula I’ve arrived at after 15y of academic and professional programming - sharing here with the purpose of having it challenged by the reader: * every abstraction has a cost - DO a quick cost/benefit analysis in your head, or even better in the code comments, when choosing for/against an abstraction. * generally, start with KISS. - a process begins with a verb and its design usually starts with being a function/procedure - pieces of data that belong together across multiple processes should start out as an immutable object or struct. In python I’m almost never using direct descendants of object, rather I inherit either from NamedTuple (for final classes) or I decorate with @dataclass(frozen=True) for non-final. * using the above, you’ll start seeing violations of DRY. DO use the rule-of-threes. If there’s a second repetition you’re either writing, or already anticipate based on the JIRA backlog - factor out the repeating code using an appropriate abstraction. I’ve found that code written with these rules tends to be simple yet clean (these two properties can often be opposite, I’ve seen simple code that is constantly repeating itself and thus becomes unmaintainable, and I’ve also seen clean code that is the opposite of simple because of an abundance of abstractions (think FizzBuzzEnterprise).

slx26 6y ago
Yes, abstractions make symbolic sense for humans, but in a technical context they are most often problematic, because intuition and technical correctness rarely align. Not like they are on opposite sides, but intuition almost always has a lot of technical holes, and when you are coding, something always ends up surfacing from those holes... and it's never pleasant. In this sense, focusing on the data and simple rules is most likely to bring us closer to the true technical problem that we are trying to solve. Abstractions and organization and good names are still vital because we do need an intuitive vision of the system as a whole, but the technical processes need to be strictly correct, not just intuitive.
fsnowdin 6y ago
That FizzBuzzEnterprise thing is hilarious. I can't believe I didn't know about it until now.

azaza123 6y ago

The problem of the article is the same as the problem of the general discussion on how to program better: quality of arguments. Instead of conducting scientific studies on code readability, programmers keep on sharing their opinions which they support with anecdotes or citations of Shakespeare. There is so much for the community to learn about...

aszen 6y ago
I think the whole point of the article was that code readability is not a scientific phenomenon you can measure by conducting studies. How readable the code is, depends on who's reading, what's their background and what style do they prefer for expressing logic.

aszen 6y ago

Code readability is just one of the goals we aim for while designing software, performance is another, stability is another, flexibility and ability to make changes is yet another. While reading any code I tend to think about these tradeoffs and see if that hard to read code is actually hard for a reason or simply a mess because no one took care of it. Writing dumb easy looking duplicate code is not optimal either, I don't see an issue with stable, fast and efficient code that's harder to understand yet works brilliantly. One can easily increase readability of such code by adding comments but one can't get performance, stability and flexibility by writing comments. Optimising for dummies just because code is easier to debug isn't a good idea, often times I have to debug easy looking code only to find that it's not that easy in execution as it was in reading. Simple code often doesn't handle all the edge cases, abstraction less code is harder to maintain and change, easy code can't evolve and grow with business needs. It's only when code is unreadable, buggy and slow that it starts to become a real mess. Also a shout out to Rich Hickey's distinction between easy and simple, creating simple code requires a lot more effort and thought and is not easy to just read and modify by dummies.

kungtotte 6y ago
I think a lot of the time people think they have performance issues when they in fact don't, likewise with stability and flexibility. In most cases, writing the readable and straightforward version first and only moving to the less readable but more X version (for any given value of X) after it's evident that you need to is the optimal solution. It's the programming equivalent to buying cheap tools first and only buying the expensive version once the cheap one breaks: If it breaks you used it enough to warrant the expensive and more durable one, and if it didn't break you didn't have to spend more money than necessary.
- aszen 6y ago
  I do see your point but let me say a bit about performance, performance matters a whole lot if your software is being used seriously all day long for getting things done in the real world. If your software is going to be someone's day job it can't afford to be slow because users would take note and complain loud and clear because it's wasting their time. Just imagine git taking 15mins for showing diffs, would you accept that for an improvement in code readability and straightforwardness. So for different industries there are different X's that matter a whole lot more than mere readability and developer convenience.

deleted 6y ago

[deleted]

29athrowaway 6y ago

This does not acknowledge that code styles can be compared in objective ways. What is more readable? # Expression 1 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 # Expression 2 10 One requires to do 9 arithmetic operations in your head, perhaps more than once if you lost count, the other one doesn't. You can compare code in terms of length, nesting, cyclomatic complexity, number of negations, number of inputs, etc. It's not just subjective bikeshedding.

bluGill 6y ago
1 is simpler in most cases because I trust the computer to get the answer, but I need to know all the explicit parts. 2 hides where it all came from for an answer which might be wrong.
- 29athrowaway 6y ago
  Usually you give each constant a name and then operate on them symbolically. If it's a simple enough operation you can skip that and just add a comment. In this example, there are 9 arithmetic operations and there are clearly more readable ways of doing this. This is the point I am trying to make. For the author of this article, using roman numerals and using arabic numerals are the same because they represent the same quantities. However, in practice, if you have 2 accountants and tell one of them to use roman numerals, the one using roman numerals will be less productive, make more mistakes and will likely be frustrated.
- luckylion 6y ago
  I agree very much. 60 * 60 * 24 * 3 vs 258200. Which one is the number of seconds in three days?
goto11 6y ago
What is the code intended to communicate? It we don't know the intention we cant say which example most clearly communicates this intention.

diegolo 6y ago

there is this quote from Clean Code by uncle Bob that I simply love. 'Avoid mental mapping: In general programmers are pretty smart people. Smart people sometimes like to show off their smarts by demonstrating their mental juggling abilities. After all, if you can reliably remember that r is the lower-cased version of the url with the host and scheme removed, then you must clearly be very smart.'

virgilp 6y ago

> “Good code is simple” doesn’t actually say anything. This is why I love Rich Hickey's "simple made easy" talk, because with it you an make the distinction between "simple" and "easy". "Good code is simple" absolutely says something and has an objective meaning, at least for some people.

jondubois 6y ago

The most important characteristics are: - Components have clear separation of concerns and well encapsulated state. (Should be easy to explain what a component does to a non-technical person). - Names of components are clear and rooted in the business domain; not made up abstract technical concepts. This relates to the first point. - Simple interfaces between components (components interact with each other through a simple, plain language; avoid passing complex instances to each other). Simple function arguments like strings, numbers and other simple pass-by-value structures are ideal. Components should be able to invoke actions on other components but the responsibility of how this is achieved lies entirely with the component who is responsible for that concern; this is also why state encapsulation is important. - Clear unidirectional data flows throughout the system. State changes for a particular kind of state should originate from a single place in the code. If you notice, all of these characteristics work together and build on top of each other. It's all or nothing. You either get all of these right or none of these right.

chrisma0 6y ago

There is a recent study (to be published at ESEM'20) on an empirical validation of "Cognitive Complexity" as a measure of source code understandability: https://arxiv.org/abs/2007.12520 https://arxiv.org/abs/2007.12520 The authors state in the conclusion: "The metric correlates with the time it takes a developer to understand source code, with a combination of time and correctness, and with subjective ratings of understandability."