3 ms·

But who talked about bad architecture? Good readable code doesn't rule out good architecture. Surely some things are complicated but even then, a dev should be

by zwnow 2y ago

But who talked about bad architecture? Good readable code doesn't rule out good architecture. Surely some things are complicated but even then, a dev should be able to quickly see whats going on with minimal expertise in a codebase.

swatcoder 2y ago
They're suggesting that readability and "5-second accessibility" are essentially contextual and build on a conceptual language that might be specific to a tool, team, or project. The novel function that might take "5 seconds to read" for the 20 people contributing to a mature project with a good architecture might nonetheless take 10 minutes for a new hire to decipher because they don't know the local vocabulary (architecture, idioms) and need to trace and interpret things elsewhere in the project and its libraries. Meanwhile, writing implementations in a way that tried to avoid a local vocabulary altogether might make naive reads easier, but less readable to experienced team member because they're not as concise as they could be. Your general advice to "make things easily readable" is good advice, but like with writing compelling prose or making accessible graphic design, you need to consider your audience and your choices might look different than the ones somebody else might make.
- hinkley 2y ago
  Go is a board game with simple rules but combinatorial consequences to those rules. Minutes to learn and a lifetime to master. This is where “simple recursive data structures” can be simple to read but difficult to track and comprehend. An architecture that descends through distinct layers at least has landmarks that the recursive one does not have. If you are not at the root or the leaf you don’t really know where you are, lost in the middle.
jacobr1 2y ago
The broader problem is "cognitive load to understand the code I'm looking at." There are a variety of factors that lead enabling that. This is a very limited example. function isReadyToDoThing(Foo foo) { return foo.ready } function processStuff((Foo foo) { if isReadyToDoThing(foo) { res = workflowA(foo) res2 = workflowB(foo) return res && res2 } } This might be dumb, if isReadyToDoThing is trivial, and it could be easily inlined. Or alternatively it could be a good way to self-document, or annotate a preferred approach (imagine several similar named methods). Regardless if you don't know the code, you'll want to go look at the method, especially if it is in a different file. But also consider: function isReadyToDoThing(Foo foo) { return foo.attribute1 && foo.attribute2 && ! otherThing(foo) } This or more complex logic might be encapsulated, in which case this is probably good to separate. Making these kind of tradeoffs involve thinking about the overall system design, not just the way you structure the code within a given function.
- maleldil 2y ago
  If `isReadyToDoThing` is only used in one place, I'd argue that it's better to inline it with an appropriately-named variable so I don't have to "go to definition" to understand what it's doing. I think people get too caught up in "small functions" and lose the readability of code locality.

by zwnow 2y ago

swatcoder 2y ago

They're suggesting that readability and "5-second accessibility" are essentially contextual and build on a conceptual language that might be specific to a tool, team, or project. The novel function that might take "5 seconds to read" for the 20 people contributing to a mature project with a good architecture might nonetheless take 10 minutes for a new hire to decipher because they don't know the local vocabulary (architecture, idioms) and need to trace and interpret things elsewhere in the project and its libraries. Meanwhile, writing implementations in a way that tried to avoid a local vocabulary altogether might make naive reads easier, but less readable to experienced team member because they're not as concise as they could be. Your general advice to "make things easily readable" is good advice, but like with writing compelling prose or making accessible graphic design, you need to consider your audience and your choices might look different than the ones somebody else might make.

hinkley 2y ago
Go is a board game with simple rules but combinatorial consequences to those rules. Minutes to learn and a lifetime to master. This is where “simple recursive data structures” can be simple to read but difficult to track and comprehend. An architecture that descends through distinct layers at least has landmarks that the recursive one does not have. If you are not at the root or the leaf you don’t really know where you are, lost in the middle.

jacobr1 2y ago

The broader problem is "cognitive load to understand the code I'm looking at." There are a variety of factors that lead enabling that. This is a very limited example. function isReadyToDoThing(Foo foo) { return foo.ready } function processStuff((Foo foo) { if isReadyToDoThing(foo) { res = workflowA(foo) res2 = workflowB(foo) return res && res2 } } This might be dumb, if isReadyToDoThing is trivial, and it could be easily inlined. Or alternatively it could be a good way to self-document, or annotate a preferred approach (imagine several similar named methods). Regardless if you don't know the code, you'll want to go look at the method, especially if it is in a different file. But also consider: function isReadyToDoThing(Foo foo) { return foo.attribute1 && foo.attribute2 && ! otherThing(foo) } This or more complex logic might be encapsulated, in which case this is probably good to separate. Making these kind of tradeoffs involve thinking about the overall system design, not just the way you structure the code within a given function.

maleldil 2y ago
If `isReadyToDoThing` is only used in one place, I'd argue that it's better to inline it with an appropriately-named variable so I don't have to "go to definition" to understand what it's doing. I think people get too caught up in "small functions" and lose the readability of code locality.