4 ms·

I think there are some basic measures of readability that could be quantified. Off the top of my head, the ratio of keywords to symbols and the density of those

I think there are some basic measures of readability that could be quantified. Off the top of my head, the ratio of keywords to symbols and the density of those keywords/symbols would make a difference. Seems like it can be specified and not just left at “is it written like I would write it,” but I can’t think of any other metrics right now.

vitus 5y ago
Some additional general comments: - Avoid deeply nested code; try to reduce "cyclomatic complexity". Refactor to use helper functions and guard statements as appropriate. - Your code shouldn't need an IDE to be understood. Among other things, this often means avoiding overuse of type deduction features like auto in C++, var in Java, etc. - A well-named function can be treated like a black box, without having to dive into its implementation to figure out what it's doing. - Simple is better than clever. For instance, just because you see an opportunity to use the Y combinator (https://en.wikipedia.org/wiki/Fixed-point_combinator#Fixed-point_combinators_in_lambda_calculus https://en.wikipedia.org/wiki/Fixed-point_combinator#Fixed-p...) or Duff's device doesn't mean that you should. - Avoid premature optimization. Only reach for it if it's proven to be a bottleneck, preferably with real-world data (as microbenchmarks are not always representative). - This one comes up most frequently in code review, and is probably the most important one: if your colleague doesn't understand your code, it might not be readable.
- passivate 5y ago
  While those are great points (thanks for writing them BTW) I do wonder if we need to have a more wide-scope approach to the various styles of code. Quoting the article > Code that's hard to understand is often a result of an accumulation of things: > The code was written at a time when the language/framework didn't do then what it does now; > The code was written a while back and the fashions and "best practices" back then were different; > Each line of code was written with readability in mind, but over time as more lines got added, the overall message was lost; > People moved on and moved away, and now you haven't got anyone to ask about the business or technical reasons behind something (and of course the documentation is horribly out of date). I would add: > The code was written to meet a budget for time/latency/size and readability became secondary to meet those requirements. E.g. systems code/firmware/OS code often have a hard limit that they need to comply with. I've had to write code for an earlier job that had to fit within 16kb - compiled, and the code was anything but readable.
  - vitus 5y ago
    Oh, that's definitely valid. It's not like your colleagues set out to write bad code, or built systems that weren't extensible (at least, I hope that's the case). But they needed to get things done, and so they did what made sense at the time. And over time, these organically-grown codebases develop more and more complexity and tend to retain historical baggage (often fueled by "if it ain't broke, don't fix it" coupled with reward structures typically not incentivizing the repaying of technical debt). (not referring to your colleagues per se, but rather another general statement) A popular fable is that of Chesterton's Fence. In short: if you don't understand why something is the way it is, then you should be wary of getting rid of it. This is incredibly applicable to refactors and clean rewrites. Starting with a good foundation is crucial, since a lot of code is inevitably patterned on surrounding code. But making sure those incremental changes over time are also of high quality is important for making sure that the code quality doesn't degrade over time, because the new code of today is the existing code of tomorrow. I sympathize with stringent product requirements -- that imposes tons of limitations on what you can reasonably do. But if you have nothing else, a comprehensive, well-structured, well-documented (and/or self-documenting) test suite can be an excellent way to document system behavior.

vitus 5y ago

Some additional general comments: - Avoid deeply nested code; try to reduce "cyclomatic complexity". Refactor to use helper functions and guard statements as appropriate. - Your code shouldn't need an IDE to be understood. Among other things, this often means avoiding overuse of type deduction features like auto in C++, var in Java, etc. - A well-named function can be treated like a black box, without having to dive into its implementation to figure out what it's doing. - Simple is better than clever. For instance, just because you see an opportunity to use the Y combinator (https://en.wikipedia.org/wiki/Fixed-point_combinator#Fixed-point_combinators_in_lambda_calculus https://en.wikipedia.org/wiki/Fixed-point_combinator#Fixed-p...) or Duff's device doesn't mean that you should. - Avoid premature optimization. Only reach for it if it's proven to be a bottleneck, preferably with real-world data (as microbenchmarks are not always representative). - This one comes up most frequently in code review, and is probably the most important one: if your colleague doesn't understand your code, it might not be readable.

passivate 5y ago
While those are great points (thanks for writing them BTW) I do wonder if we need to have a more wide-scope approach to the various styles of code. Quoting the article > Code that's hard to understand is often a result of an accumulation of things: > The code was written at a time when the language/framework didn't do then what it does now; > The code was written a while back and the fashions and "best practices" back then were different; > Each line of code was written with readability in mind, but over time as more lines got added, the overall message was lost; > People moved on and moved away, and now you haven't got anyone to ask about the business or technical reasons behind something (and of course the documentation is horribly out of date). I would add: > The code was written to meet a budget for time/latency/size and readability became secondary to meet those requirements. E.g. systems code/firmware/OS code often have a hard limit that they need to comply with. I've had to write code for an earlier job that had to fit within 16kb - compiled, and the code was anything but readable.
- vitus 5y ago
  Oh, that's definitely valid. It's not like your colleagues set out to write bad code, or built systems that weren't extensible (at least, I hope that's the case). But they needed to get things done, and so they did what made sense at the time. And over time, these organically-grown codebases develop more and more complexity and tend to retain historical baggage (often fueled by "if it ain't broke, don't fix it" coupled with reward structures typically not incentivizing the repaying of technical debt). (not referring to your colleagues per se, but rather another general statement) A popular fable is that of Chesterton's Fence. In short: if you don't understand why something is the way it is, then you should be wary of getting rid of it. This is incredibly applicable to refactors and clean rewrites. Starting with a good foundation is crucial, since a lot of code is inevitably patterned on surrounding code. But making sure those incremental changes over time are also of high quality is important for making sure that the code quality doesn't degrade over time, because the new code of today is the existing code of tomorrow. I sympathize with stringent product requirements -- that imposes tons of limitations on what you can reasonably do. But if you have nothing else, a comprehensive, well-structured, well-documented (and/or self-documenting) test suite can be an excellent way to document system behavior.