7 ms·

Why would it be a problem to write code in a way that's easily understood by others reading it? If your code is so complicated that a little bit of documentatio

Why would it be a problem to write code in a way that's easily understood by others reading it? If your code is so complicated that a little bit of documentation can't explain it or at least help get people started then you're probably being too "clever" with your code and need to simplify it a bit. Simple code doesn't mean it has to be under-engineered or non-performant, and creating a culture that doesn't take the time to help others understand what's going on is how teams get to the point of depending entirely on 2 people to do all their enhancements/fixes.

derekp7 5y ago
Because sometimes the clever code may be easier to understand by an experienced developer even if it is less accessible to a less experienced developer. Non-coding example: "Two plus Three times Five" is easy to understand, because you don't need to know math symbols. But to anyone who knows math, "2 + 3 * 5" is easier/quicker to read. For a coding example, in Javascript you have things like arrow functions that make the code more concise. But that is also harder to read for someone who hasn't picked up on them yet (which may have been the case when they were first introduced).
- lamplovin 5y ago
  I agree with you on language syntax choices, but as far as the articles examples are concerned it seemed like the "clever" solutions to them were more about OO architecture choices via abstraction for example. In which case, if it's not a codebase that you have experience in, then those architecture choices can get very confusing if not properly documented
- tejtm 5y ago
  It is ambiguous, "Two plus Three times Five" as a sentence reads and is naturally processed from left to right for a result of " is twenty-five". But to anyone who knows math (precedence), "2 + 3 * 5 = 17"
  - jaywalk 5y ago
    The order of operations doesn't change because the equation is written out in English versus mathematical notation.
    - foobar2021 5y ago
      How do you say and/or spell out parentheses?
      - elzbardico 5y ago
        Easy: Take two plus five and multiply it by six
      - deleted 5y ago
        [deleted]
    - perl4ever 5y ago
      "There is no ambiguity because my context is the only context" I learned a few years back that lawyers will give you a bunch of "ands" and "ors" in an expression without any concept of precedence. That doesn't necessarily mean left to right works, either.
  - ghaff 5y ago
    Yeah. That's a trivial case but I'd still probably use parentheses). For more complex precedence operations I definitely would.
- lamontcg 5y ago
  That's watered down and overly simplified. We can have an argument over ternary operators and new users and I'm going to argue that they're part of the common vernacular of computer science and everyone needs to sit down and learn them. But nested ternaries three levels deep are horrendous. Stick with one level and simple expressions and keep it readable (assuming the background of just understanding the operator). Don't overuse it. Similarly lambda functions are part of the vernacular, everyone is going to need to learn that necessary amount of complexity. But at some point nested lambda functions containing lambda functions are going to get difficult to read and reason about.
908B64B197 5y ago
The real problem is that the while the same code might look obvious to John Carmack, it might not look obvious to $outsourced_bodyshop_ressource_0443434. Then you start coding for the lowest common denominator.
- runawaybottle 5y ago
  What if the NYTimes had journalists that described the news in their specific prose or worse, poetically. Speak plainly, it’s the news, report it as plainly and accurately as possible. Often many people like to attach mathematics and science to Software Engineering to signal elitism, but truthfully this profession is a lot closer to writing. Write clearly, first and foremost, and above all else. $outsourced_bodyshop_ressource_0443434 needs to be able to read the news too.
  - 908B64B197 5y ago
    "Let's not use inheritance, it's complicated and could confuse programmers. Better to just copy-paste code." "Source control? I don't know, this git command line is a little bit too much. Let's just use zip files and email the source"
    - runawaybottle 5y ago
      That is not what I am suggesting, but alas, you seemed to have proven my point. I did not write clearly enough, and behold the outcome. Now imagine if we all do this in a codebase.
      - 908B64B197 5y ago
        What were you suggesting?
      - andrewflnr 5y ago
        Your writing was fine. HN is big enough that you can't take a single critical comment as strong evidence you were unclear. Maybe it's them, not you.
windows2020 5y ago
IME, writing code as concise as possible (semantically and syntactically) is almost always the best route. I don't believe superfluous assignments, parenthesis, braces, visibility modifiers or comments make things more easily understood by others. In time, experience and mastery of the language will reveal superfluous code as something that does the opposite as well as much cleverness as mere utilization of the language or abstraction.
- blacktriangle 5y ago
  That's the key...in time. In time doesn't help when the majority of your devs are junior which is a common case in large internal dev shops.
  - windows2020 5y ago
    How will they learn to better express logic or master the language without experience?
    - Pet_Ant 5y ago
      They won’t. They’ll be mentoring other juniors and then onto management long before then.
    - JanisL 5y ago
      I think this blog post is highly relevant https://daedtech.com/how-developers-stop-learning-rise-of-the-expert-beginner/ https://daedtech.com/how-developers-stop-learning-rise-of-th...
- watwut 5y ago
  Strongly disagree. Working on codevase that was written by "short is better" people was harder and I hated it. I don't care for your saved strokes. Make it apparent.
  - windows2020 5y ago
geoffjentry 5y ago
> that's easily understood by others reading it? The problem in these discussions always comes back to "others" aren't a monolithic entity. Different people find different things to be readable vs not. Different people will even use the exact same phrases (e.g. "as concise as possible without being opaque!") but still mean different things due to having different interpretations of key words in those phrases.

derekp7 5y ago

Because sometimes the clever code may be easier to understand by an experienced developer even if it is less accessible to a less experienced developer. Non-coding example: "Two plus Three times Five" is easy to understand, because you don't need to know math symbols. But to anyone who knows math, "2 + 3 * 5" is easier/quicker to read. For a coding example, in Javascript you have things like arrow functions that make the code more concise. But that is also harder to read for someone who hasn't picked up on them yet (which may have been the case when they were first introduced).

lamplovin 5y ago
I agree with you on language syntax choices, but as far as the articles examples are concerned it seemed like the "clever" solutions to them were more about OO architecture choices via abstraction for example. In which case, if it's not a codebase that you have experience in, then those architecture choices can get very confusing if not properly documented
tejtm 5y ago
It is ambiguous, "Two plus Three times Five" as a sentence reads and is naturally processed from left to right for a result of " is twenty-five". But to anyone who knows math (precedence), "2 + 3 * 5 = 17"
- jaywalk 5y ago
  The order of operations doesn't change because the equation is written out in English versus mathematical notation.
  - foobar2021 5y ago
    How do you say and/or spell out parentheses?
    - elzbardico 5y ago
      Easy: Take two plus five and multiply it by six
    - deleted 5y ago
      [deleted]
  - perl4ever 5y ago
    "There is no ambiguity because my context is the only context" I learned a few years back that lawyers will give you a bunch of "ands" and "ors" in an expression without any concept of precedence. That doesn't necessarily mean left to right works, either.
- ghaff 5y ago
  Yeah. That's a trivial case but I'd still probably use parentheses). For more complex precedence operations I definitely would.
lamontcg 5y ago
That's watered down and overly simplified. We can have an argument over ternary operators and new users and I'm going to argue that they're part of the common vernacular of computer science and everyone needs to sit down and learn them. But nested ternaries three levels deep are horrendous. Stick with one level and simple expressions and keep it readable (assuming the background of just understanding the operator). Don't overuse it. Similarly lambda functions are part of the vernacular, everyone is going to need to learn that necessary amount of complexity. But at some point nested lambda functions containing lambda functions are going to get difficult to read and reason about.

908B64B197 5y ago

The real problem is that the while the same code might look obvious to John Carmack, it might not look obvious to $outsourced_bodyshop_ressource_0443434. Then you start coding for the lowest common denominator.

runawaybottle 5y ago
What if the NYTimes had journalists that described the news in their specific prose or worse, poetically. Speak plainly, it’s the news, report it as plainly and accurately as possible. Often many people like to attach mathematics and science to Software Engineering to signal elitism, but truthfully this profession is a lot closer to writing. Write clearly, first and foremost, and above all else. $outsourced_bodyshop_ressource_0443434 needs to be able to read the news too.
- 908B64B197 5y ago
  "Let's not use inheritance, it's complicated and could confuse programmers. Better to just copy-paste code." "Source control? I don't know, this git command line is a little bit too much. Let's just use zip files and email the source"
  - runawaybottle 5y ago
    That is not what I am suggesting, but alas, you seemed to have proven my point. I did not write clearly enough, and behold the outcome. Now imagine if we all do this in a codebase.
    - 908B64B197 5y ago
      What were you suggesting?
    - andrewflnr 5y ago
      Your writing was fine. HN is big enough that you can't take a single critical comment as strong evidence you were unclear. Maybe it's them, not you.

windows2020 5y ago

IME, writing code as concise as possible (semantically and syntactically) is almost always the best route. I don't believe superfluous assignments, parenthesis, braces, visibility modifiers or comments make things more easily understood by others. In time, experience and mastery of the language will reveal superfluous code as something that does the opposite as well as much cleverness as mere utilization of the language or abstraction.

blacktriangle 5y ago
That's the key...in time. In time doesn't help when the majority of your devs are junior which is a common case in large internal dev shops.
- windows2020 5y ago
  How will they learn to better express logic or master the language without experience?
  - Pet_Ant 5y ago
    They won’t. They’ll be mentoring other juniors and then onto management long before then.
  - JanisL 5y ago
    I think this blog post is highly relevant https://daedtech.com/how-developers-stop-learning-rise-of-the-expert-beginner/ https://daedtech.com/how-developers-stop-learning-rise-of-th...
watwut 5y ago
Strongly disagree. Working on codevase that was written by "short is better" people was harder and I hated it. I don't care for your saved strokes. Make it apparent.
- windows2020 5y ago

geoffjentry 5y ago

> that's easily understood by others reading it? The problem in these discussions always comes back to "others" aren't a monolithic entity. Different people find different things to be readable vs not. Different people will even use the exact same phrases (e.g. "as concise as possible without being opaque!") but still mean different things due to having different interpretations of key words in those phrases.