4 ms·

Part of the problem is that "well written code" is unbelievably subjective. Take 10 people from hacker news and you will get 10 likely very different answers, s

Part of the problem is that "well written code" is unbelievably subjective. Take 10 people from hacker news and you will get 10 likely very different answers, some of them most likely the exact opposites. Maybe it has to do with being "a new industry", but by now we have accumulated decades. I think it's more because you can get away with it. In other industries, you can't. If a bridge collapses, people die. If a car's brakes fail, people die. If you administer the wrong amount of anesthesia, people die. If you write spaghetti code .. shrug and move on. Even within the code base of the place I work in, a few hundred sw engs in total, we don't have a shared understanding of what exactly "good", "clean", ... design is. Everybody has an idea, and there are overlaps, but the criteria that people seem to optimize for, and thus the conclusions they draw about design, differ vastly. Within my company, and even more so across our industry.

catlifeonmars 6y ago
Heh, good code is the kind you can throw away once you’ve used it to sell stakeholders on an idea. It’s contextual. Or, to put it another way: is a very structurally sound bridge located on a road that no one uses considered a “good” bridge?
- Grimm1 6y ago
  I'd raise a difference between good and useful then. That is still a good bridge, but it's not a useful one. I think that also transfers to programming. That also raises that what makes a bridge good is not usefulness it's perhaps structural quality. Maybe the only thing that makes programming good is usefulness in which case my point is moot.
adam_arthur 6y ago
There's subjectivity, but you can also certainly make objective arguments for why one form is readable relative to others. For example, here are some principles I can strongly justify: Bubble important info. Structure your code visually such that signal to noise ratio is highest. E.g. appropriately named variables should be more immediately visible than implementation details. E.g. if variable is named well, you can typically ignore the RHS of an assignment... It's an implementation detail. Don't indent such that RHS of assignment is emphasized. We can debate that point, but I'm using objective reasoning for defining why this style is beneficial. Human readable naming. Name of variables should define exactly what they represent and nothing else. Your code should be written to read as closely to natural language as possible. E.g. if in a functional language, and all functions describe what they do exactly, RHS of assignments are indented to deemphasize them, you can understand high level of any function quickly by scanning LHS assignments and top level expressions. The more unclear your names, the more "mental recalls or lookups" the reader has to do. Don't use anonymous functions. For anything longer than one line, always used a named function that appropriately represents what it does. Reader should not ever get implementation details pushed into their face. Pushing implementation details to the forefront is the biggest readability error I see in code. It's almost never important for business oriented code unless there's a bug in it. Majority of the time the reader is simply trying to get context and understand meaning of the code. Optimize for this. Hide your declared functions out of sight. Reader will get high level understanding of their use where called, due to their name. If they want to reference the implementation, they can go to function declaration, but typically they won't need to. Don't declare functions sibling to your core logic. They should not break high level flow of function (does not help readability). Frustrating when people declare functions above where the core logic of the function is... See it a lot in python due to lack of inner function hoisting. Books have footnotes for a reason Hide implementation details as much as possible behind api boundaries. Model component apis such that implementation details are not exposed to caller or creator. Don't mix naming of business concepts and render logic. E.g. if you have a generic graph component, nothing within that component should reference your business domain. I see this mistake a lot. More generally, never name something which implies an understanding of a different context than the one you're in. By doing so you're coupling the two domains and increasing the amount of context the reader needs to understand your code. Prefer immutable variables. The more constants and immutable state you use, the fewer things you have to track in your head as you follow code. You know once you see an assignment, that variable will never change. You don't need to scan every line between assignment and later use to determine whether that var is later modified. Don't nest expressions too deeply, such that it's difficult to parse. If you can instead assign to appropriately named variable, reader can typically ignore the expression altogether. Prefer named function or variable that describe the result of a computation rather than inlining an expression. If featureFlag == 1 represents isFeatureEnabled, assign that to an appropriately named variable. Anytime you make the reader "infer the name" of a variable by parsing the expression themselves, you make your code harder to read. camelCase is superior to snake_case because a variable represents a single concept, not separate concepts represented by a string of words. Adding underscore unnecessarily makes words visually distinct when you're dealing with a single concept. They also add verbosity and length that doesn't benefit anything. Is there an objective argument for snake case being more readable other than it's the convention in some languages (not objective reasoning) (Flame war go!) Anyway, I could go on with a number of more points. Am I suggesting there's a correct style? Not at all. But you can absolutely use strong and objective reasoning for why one style is superior to another. I don't see people typically apply this kind of rigor to their style, they tend to just prefer one approach "because". Different people will weight things differently, so can come to different conclusion given same evidence, but there's absolutely a whole set of philosophy and logic you can use to justify style, and it's not explored at all in academia really. Final note. There is definitely an element of cultural bias as well. People who tend to read code of one style will more readily be able to parse that style. There is no universal truth. But if we all start from the same state, we should justify which styles are best with strong reasoning.
- hnedeotes 6y ago
  Because I agree with most of it, but you called for a flame war, I'm going to jump in. snake_case, is obviously the more readable. In fact your point shows this cognitive dissonance we all have to a certain extent. You argued (and I agree) with a lot of details that are important for readability at "first sight", "intuitive layout" etc, and then you go to say camelCase is more readable... We're not even taking into account people with small amounts of dyslexia in this, but certainlyThisIsNotMoreReadable than certainly_this_is_not_more_readable Is it? :) gzip will take care of the underscores
  - anaerobicover 6y ago
    They're both pinkie cases -- kebab case is clearly superior. ;)
    - hnedeotes 6y ago
      Maybe if you're a foodie person? :) kebab doesn't allow to do whole selections on most text interfaces though so that's a real downer for me, no matter how much a good kebab is worth
  - adam_arthur 6y ago
    Well, I regret putting that part in, as I was just trying to be cheeky :) It took away from my overall point, as I don't have strong convictions on that one. That one is much more subjective than the other points!
- wildmanx 6y ago
  Thanks for this long list. But again, that's missing the point. Everybody has their list of what they do and why. And everybody is pretty convinced that this is how it ought to be and they have good reasons. I'm not saying yours are wrong. But for most of your points, I know people who'd argue the exact opposite. And they give good reasons too. Point is that we don't have a shared, common, well-defined core in our industry. A list that everybody adheres to. Our lists are not in sync. The variety of programming languages that people can choose from now does not help either. Standard practice in one language is a cardinal sin in another. Different patterns, different principles, different paradigms. People mix and match freely.
kansface 6y ago
> Part of the problem is that "well written code" is unbelievably subjective. I'd recommend you check out Code Complete if you haven't read it. It is an excellent intro into best practices although its about 1000 pages and a bit dated. As it turns out, we as an industry do have an understanding of what makes code better, and it turns out, its mostly not very controversial - push complexity as low as it can go, simpler interfaces tend to be better, argument pass through causes errors, functions longer than 80 lines are associated with higher error counts, optimize code for human comprehension later (~70% of the effort that goes into code is maintaining it) etc etc.
- wildmanx 6y ago
  What I personally check out does not matter much. My point was a lack of consensus within the industry. It does not help if I read the same book as you and we two agree 100% what exactly we mean, when the next guy considers most of that nonsense. And that's what I observe with colleagues. > it turns out, its mostly not very controversial I don't believe this until proven otherwise with actual data. Any programming concept on this planet eventually gets an article on the HN front page that argues for why that particular concept is really bad and then we are having a huge discussion about it.
  - luord 6y ago
    > I don't believe this until proven otherwise with actual data. I don't remember the last time that a piece by Uncle Bob or Martin Fowler—and they're just two examples, I've seen quite a few more who are generally met with agreement every time they're posted—was heavily criticized or disagreed with here. And when I do see disagreements, they tend to come from people who don't seem to have nearly as much experience as those guys do or who might have misinterpreted their point (much like how the idea of agile has turned into something that only reflects the manifesto tangentially, and accidentally at that) and who are, perhaps not coincidentally, likely to fall in the "programming is easy" camp. And even then, "controversial in hacker news" is hardly representative of what's controversial in the field at large (which I also understand goes against my own first point).
- 6y ago

catlifeonmars 6y ago

Heh, good code is the kind you can throw away once you’ve used it to sell stakeholders on an idea. It’s contextual. Or, to put it another way: is a very structurally sound bridge located on a road that no one uses considered a “good” bridge?

Grimm1 6y ago
I'd raise a difference between good and useful then. That is still a good bridge, but it's not a useful one. I think that also transfers to programming. That also raises that what makes a bridge good is not usefulness it's perhaps structural quality. Maybe the only thing that makes programming good is usefulness in which case my point is moot.

adam_arthur 6y ago

There's subjectivity, but you can also certainly make objective arguments for why one form is readable relative to others. For example, here are some principles I can strongly justify: Bubble important info. Structure your code visually such that signal to noise ratio is highest. E.g. appropriately named variables should be more immediately visible than implementation details. E.g. if variable is named well, you can typically ignore the RHS of an assignment... It's an implementation detail. Don't indent such that RHS of assignment is emphasized. We can debate that point, but I'm using objective reasoning for defining why this style is beneficial. Human readable naming. Name of variables should define exactly what they represent and nothing else. Your code should be written to read as closely to natural language as possible. E.g. if in a functional language, and all functions describe what they do exactly, RHS of assignments are indented to deemphasize them, you can understand high level of any function quickly by scanning LHS assignments and top level expressions. The more unclear your names, the more "mental recalls or lookups" the reader has to do. Don't use anonymous functions. For anything longer than one line, always used a named function that appropriately represents what it does. Reader should not ever get implementation details pushed into their face. Pushing implementation details to the forefront is the biggest readability error I see in code. It's almost never important for business oriented code unless there's a bug in it. Majority of the time the reader is simply trying to get context and understand meaning of the code. Optimize for this. Hide your declared functions out of sight. Reader will get high level understanding of their use where called, due to their name. If they want to reference the implementation, they can go to function declaration, but typically they won't need to. Don't declare functions sibling to your core logic. They should not break high level flow of function (does not help readability). Frustrating when people declare functions above where the core logic of the function is... See it a lot in python due to lack of inner function hoisting. Books have footnotes for a reason Hide implementation details as much as possible behind api boundaries. Model component apis such that implementation details are not exposed to caller or creator. Don't mix naming of business concepts and render logic. E.g. if you have a generic graph component, nothing within that component should reference your business domain. I see this mistake a lot. More generally, never name something which implies an understanding of a different context than the one you're in. By doing so you're coupling the two domains and increasing the amount of context the reader needs to understand your code. Prefer immutable variables. The more constants and immutable state you use, the fewer things you have to track in your head as you follow code. You know once you see an assignment, that variable will never change. You don't need to scan every line between assignment and later use to determine whether that var is later modified. Don't nest expressions too deeply, such that it's difficult to parse. If you can instead assign to appropriately named variable, reader can typically ignore the expression altogether. Prefer named function or variable that describe the result of a computation rather than inlining an expression. If featureFlag == 1 represents isFeatureEnabled, assign that to an appropriately named variable. Anytime you make the reader "infer the name" of a variable by parsing the expression themselves, you make your code harder to read. camelCase is superior to snake_case because a variable represents a single concept, not separate concepts represented by a string of words. Adding underscore unnecessarily makes words visually distinct when you're dealing with a single concept. They also add verbosity and length that doesn't benefit anything. Is there an objective argument for snake case being more readable other than it's the convention in some languages (not objective reasoning) (Flame war go!) Anyway, I could go on with a number of more points. Am I suggesting there's a correct style? Not at all. But you can absolutely use strong and objective reasoning for why one style is superior to another. I don't see people typically apply this kind of rigor to their style, they tend to just prefer one approach "because". Different people will weight things differently, so can come to different conclusion given same evidence, but there's absolutely a whole set of philosophy and logic you can use to justify style, and it's not explored at all in academia really. Final note. There is definitely an element of cultural bias as well. People who tend to read code of one style will more readily be able to parse that style. There is no universal truth. But if we all start from the same state, we should justify which styles are best with strong reasoning.

hnedeotes 6y ago
Because I agree with most of it, but you called for a flame war, I'm going to jump in. snake_case, is obviously the more readable. In fact your point shows this cognitive dissonance we all have to a certain extent. You argued (and I agree) with a lot of details that are important for readability at "first sight", "intuitive layout" etc, and then you go to say camelCase is more readable... We're not even taking into account people with small amounts of dyslexia in this, but certainlyThisIsNotMoreReadable than certainly_this_is_not_more_readable Is it? :) gzip will take care of the underscores
- anaerobicover 6y ago
  They're both pinkie cases -- kebab case is clearly superior. ;)
  - hnedeotes 6y ago
    Maybe if you're a foodie person? :) kebab doesn't allow to do whole selections on most text interfaces though so that's a real downer for me, no matter how much a good kebab is worth
- adam_arthur 6y ago
  Well, I regret putting that part in, as I was just trying to be cheeky :) It took away from my overall point, as I don't have strong convictions on that one. That one is much more subjective than the other points!
wildmanx 6y ago
Thanks for this long list. But again, that's missing the point. Everybody has their list of what they do and why. And everybody is pretty convinced that this is how it ought to be and they have good reasons. I'm not saying yours are wrong. But for most of your points, I know people who'd argue the exact opposite. And they give good reasons too. Point is that we don't have a shared, common, well-defined core in our industry. A list that everybody adheres to. Our lists are not in sync. The variety of programming languages that people can choose from now does not help either. Standard practice in one language is a cardinal sin in another. Different patterns, different principles, different paradigms. People mix and match freely.

kansface 6y ago

> Part of the problem is that "well written code" is unbelievably subjective. I'd recommend you check out Code Complete if you haven't read it. It is an excellent intro into best practices although its about 1000 pages and a bit dated. As it turns out, we as an industry do have an understanding of what makes code better, and it turns out, its mostly not very controversial - push complexity as low as it can go, simpler interfaces tend to be better, argument pass through causes errors, functions longer than 80 lines are associated with higher error counts, optimize code for human comprehension later (~70% of the effort that goes into code is maintaining it) etc etc.

wildmanx 6y ago
What I personally check out does not matter much. My point was a lack of consensus within the industry. It does not help if I read the same book as you and we two agree 100% what exactly we mean, when the next guy considers most of that nonsense. And that's what I observe with colleagues. > it turns out, its mostly not very controversial I don't believe this until proven otherwise with actual data. Any programming concept on this planet eventually gets an article on the HN front page that argues for why that particular concept is really bad and then we are having a huge discussion about it.
- luord 6y ago
  > I don't believe this until proven otherwise with actual data. I don't remember the last time that a piece by Uncle Bob or Martin Fowler—and they're just two examples, I've seen quite a few more who are generally met with agreement every time they're posted—was heavily criticized or disagreed with here. And when I do see disagreements, they tend to come from people who don't seem to have nearly as much experience as those guys do or who might have misinterpreted their point (much like how the idea of agile has turned into something that only reflects the manifesto tangentially, and accidentally at that) and who are, perhaps not coincidentally, likely to fall in the "programming is easy" camp. And even then, "controversial in hacker news" is hardly representative of what's controversial in the field at large (which I also understand goes against my own first point).
6y ago