3 ms·

Writing readable code is not "nitpicking". It is common that an author doesn't see why their parameter name or function name is misleading but their reviewer, w

Writing readable code is not "nitpicking". It is common that an author doesn't see why their parameter name or function name is misleading but their reviewer, who comes to the change without as many preconceptions, sees it right away.

dontreact 3y ago
Im not saying it’s always nitpicking. I’m saying that sometimes it is.
bheadmaster 3y ago
"Readable" and "misleading" are subjective, and depend on the person's "preconceptions". I disagree that the reviewer comes "without as many preconceptions" - they just come with different preconceptions, the ones they're used to. Programming language is a language like any other, and each person has their own style of writing it, and they'd prefer the rest of the world to use their own style because it's "more readable".
- tikhonj 3y ago
  Are you saying there is no such thing as clearer or less clear writing in natural languages or programming languages? It's 100% subjective and depends entirely on the reader?
  - bheadmaster 3y ago
    Of course, it's not 100% subjective - rarely anything in the world is 100% anything. But I think that most people consider their personal preferences to be better and more readable just because they're used to them, so I tend to take the opposite attitude as the starting point. There were more than a few situations where I've had a coworker tell me "just read the code, it's very readable", only to spend the next two weeks just trying to figure out how it works. Sure, once you figure out how it works and it "clicks", it's no longer (that) unreadable, but the fact that I have to spend so much time reading the codebase in the first place made me convinced that personal familiarity is a great part of what "readable" means.
  - KptMarchewa 3y ago
    I believe overtly verbose, enterprise Java names make code _less_ clear in modern times with proper development tools. Entire group of people has to think otherwise due to proliferation of that style.
  - TeMPOraL 3y ago
    Some thing are objectively bad. But a lot is up to, if not subjective preferences, then at least situational ones. With modern programming languages, we're operating close to Pareto frontier in terms of expressiveness - there's just no way to make a piece of plaintext code more readable for some readers, without sacrificing readability for other readers with different goals. Things like "lots of small functions vs. few large functions", or "exceptions vs. sum type return value", are such cases - they seem subjective, but they're less about preferences, and more about the kind of work a given reader is doing. Either choice is better than the other for some kind of work. We can't improve on this until we move past working directly on plaintext, single-source-of-truth codebases. Plaintext is fine. Single source of truth is obviously needed. The problem is with insistence on only ever working directly on it, which leads to a futile attempt at inventing styles and languages that would express every cross-cutting concern and needs of every job in a clear and readable fashion. It's just not possible. (And yes, I believe the bleeding edge of programming language development is effectively just spinning the wheels now - adding increasingly complex abstract math to programming languages isn't going to help square the circle.)
- jeffbee 3y ago
  Can't agree here. Often an author is writing code and they start with a tentative function, parameter, variable, or type name, then as the change progresses the semantics of the thing changed but the name stayed the same. Authors won't always see this but reviewers are more likely to notice it.
faster 3y ago
I struggle with this. I work with devs who think that a function with 3 side effects is fine, and suggestions that it would be more maintainable if it did one thing (and even more offensive, that the function name should be a clue to what the function does) are often met with hostility. In the end they're angry and resistant and I'm frustrated. Sometimes I just approve it, write a technical debt ticket, and move on.
- runlevel1 3y ago
  Anger and frustration is obviously not an appropriate response to constructive feedback offered in earnest, but do you have any insight into why they respond that way? Like naïveté as to why it's usually a bad idea to do that, them misinterpreting your intent, or redirected aggression from another source of frustration (like workload, deadlines, etc.)?
seanmcdirmid 3y ago
If it truly a matter of readability, then it really isn't a nitpick. If it is a matter of "I think doing X is slightly better than doing Y, and if you start doing X rather than Y, that would improve things somewhat", then it is a nit. To put it this way, you should use Kotlin vals with get methods with getters rather than fun getXXX() functions, but this is controversial, so I always suggest it as a nit (Nit: maybe use val xxx get() = ... rather than fun getXXX() = ...).

dontreact 3y ago

Im not saying it’s always nitpicking. I’m saying that sometimes it is.

bheadmaster 3y ago

"Readable" and "misleading" are subjective, and depend on the person's "preconceptions". I disagree that the reviewer comes "without as many preconceptions" - they just come with different preconceptions, the ones they're used to. Programming language is a language like any other, and each person has their own style of writing it, and they'd prefer the rest of the world to use their own style because it's "more readable".

tikhonj 3y ago
Are you saying there is no such thing as clearer or less clear writing in natural languages or programming languages? It's 100% subjective and depends entirely on the reader?
- bheadmaster 3y ago
  Of course, it's not 100% subjective - rarely anything in the world is 100% anything. But I think that most people consider their personal preferences to be better and more readable just because they're used to them, so I tend to take the opposite attitude as the starting point. There were more than a few situations where I've had a coworker tell me "just read the code, it's very readable", only to spend the next two weeks just trying to figure out how it works. Sure, once you figure out how it works and it "clicks", it's no longer (that) unreadable, but the fact that I have to spend so much time reading the codebase in the first place made me convinced that personal familiarity is a great part of what "readable" means.
- KptMarchewa 3y ago
  I believe overtly verbose, enterprise Java names make code _less_ clear in modern times with proper development tools. Entire group of people has to think otherwise due to proliferation of that style.
- TeMPOraL 3y ago
  Some thing are objectively bad. But a lot is up to, if not subjective preferences, then at least situational ones. With modern programming languages, we're operating close to Pareto frontier in terms of expressiveness - there's just no way to make a piece of plaintext code more readable for some readers, without sacrificing readability for other readers with different goals. Things like "lots of small functions vs. few large functions", or "exceptions vs. sum type return value", are such cases - they seem subjective, but they're less about preferences, and more about the kind of work a given reader is doing. Either choice is better than the other for some kind of work. We can't improve on this until we move past working directly on plaintext, single-source-of-truth codebases. Plaintext is fine. Single source of truth is obviously needed. The problem is with insistence on only ever working directly on it, which leads to a futile attempt at inventing styles and languages that would express every cross-cutting concern and needs of every job in a clear and readable fashion. It's just not possible. (And yes, I believe the bleeding edge of programming language development is effectively just spinning the wheels now - adding increasingly complex abstract math to programming languages isn't going to help square the circle.)
jeffbee 3y ago
Can't agree here. Often an author is writing code and they start with a tentative function, parameter, variable, or type name, then as the change progresses the semantics of the thing changed but the name stayed the same. Authors won't always see this but reviewers are more likely to notice it.

faster 3y ago

I struggle with this. I work with devs who think that a function with 3 side effects is fine, and suggestions that it would be more maintainable if it did one thing (and even more offensive, that the function name should be a clue to what the function does) are often met with hostility. In the end they're angry and resistant and I'm frustrated. Sometimes I just approve it, write a technical debt ticket, and move on.

runlevel1 3y ago
Anger and frustration is obviously not an appropriate response to constructive feedback offered in earnest, but do you have any insight into why they respond that way? Like naïveté as to why it's usually a bad idea to do that, them misinterpreting your intent, or redirected aggression from another source of frustration (like workload, deadlines, etc.)?

seanmcdirmid 3y ago

If it truly a matter of readability, then it really isn't a nitpick. If it is a matter of "I think doing X is slightly better than doing Y, and if you start doing X rather than Y, that would improve things somewhat", then it is a nit. To put it this way, you should use Kotlin vals with get methods with getters rather than fun getXXX() functions, but this is controversial, so I always suggest it as a nit (Nit: maybe use val xxx get() = ... rather than fun getXXX() = ...).