4 ms·
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 principle
by 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 agoBecause 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 agoThey're both pinkie cases -- kebab case is clearly superior. ;)
- hnedeotes 6y agoMaybe 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 agoWell, 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 agoThanks 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.