4 ms·

The examples give me the creeps. How can one obsess over readability of code (in form of comments) but not think about writing readable code?! For example:

by buster 5y ago

The examples give me the creeps. How can one obsess over readability of code (in form of comments) but not think about writing readable code?! For example: cell\* run(string s) { stringstream in(s); return run(in); } What is "s"?! What is "in"?! What the hell does "run" do?! All this code commenting (which is bound to deviate from the implementation!) but no thought into naming and structuring code in an easy to understand fashion. Replace "run()" with what it actually does even if it means naming the function "replaceAllNamesInTheInputStringByDoingAFancyComputation()" or whatever. It's all better then "run()". Replace the variables with easy to understand names! I'd be mad as hell if my colleagues wrote that code.

engmgrmgr 5y ago
Effort to refactor is something to consider, and verbosity makes this harder as you get lower level. Another thing to consider is the very verbose names can be something that people actively avoid for clean code, and you could end up with spaghetti code to make it both readable and verbose (imagine someone doing this for years and then handing the code off to someone when they leave because they were so pigeonholed in that system that no one else could easily collaborate). Downstream, you can end up with tech debt instead of optimally refactored code as people struggle to do something of a smaller scope. And if every tiny thing is unit tested, it gets even harder to change without expanding the scope of work. Math code is an extreme example of where verbosity can quickly become detrimental.
- lionkor 5y ago
 Definitely have to disagree. "Clean" code is often an excuse for lazy, short names which need a comment to explain them. Consider this completely fabricated example: // calculates the area of a rectangle with sides a and b, u being true for metric, false for imperial int rarea(int a, int b, bool u); versus int rectangle_area(int side_a, int side_b, bool metric); which more or less doesnt even need a comment anymore. "Clean code" people want short names, massive comments that can be collapsed, so that from really far away, it looks neat. Its a terrible beginner mistake I see time and time again, and it shouldnt be defended. If you write a math formula, how is writing "side_a" or "phi" worse than "a" and "p"?
 - dottedmag 5y ago
 `bool metric` does not ring any bells (I never lived in US, so I had to refer to the comment to understand it), and units of `a` and `b` and result are missing.
 - mst 5y ago
 I'd imagine in an ideal world they'd've gone with `enum(Metric, Imperial) units` but as a direct rewrite of the original function signature it was probably the least worst available option.
 - lionkor 5y ago
 `bool metric` implies that `metric` can be YES or NO, that's clearer than what was there before. Its a made-up example, this discussion is about style, not about semantics. To please those who would like to see a semantically improved version: (C++) enum class Unit { Meter, Inch, Foot, // ... }; template<Unit U> struct UnitValue { double value; }; template<Unit U> UnitValue rectangle_area(UnitValue side_a, UnitValue side_b); // invocation example constexpr Unit unit = Unit::Meter; UnitValue<unit> result = rectangle_area<unit>({5.3}, {1.5}); std::cout << result.value << std::endl; There is still room for improvement, maybe some concepts to further generify it, some more comments, maybe a PDF with full documentation, ...
 - engmgrmgr 5y ago
 Why would it be worse? Why would you write p instead of phi? I would, however, point out that to call this function, you need to separately compute lengths of sides. Where do those come from? How are coordinates stored? How are you wiring all this up? What happens when you change the data to support more dimensions, or to use memory pools, or to add new shapes? To be clear, a lot of math needs a ton of complex code, and you also often have algorithms optimized for performance, approximation, numerical stability, etc. You can encode your understanding of what’s going on in the naming and break it into chunks so it’s readable, but that’s not necessarily a good thing. Write some code to compute the intersecting earth-surface geometry of the projected frustum far planes from two satellites’ cameras at some point in time. Who’s using this code, is it a library? How do you abstract it? Who are the consumers of the code, will they ever change it or only use a part of it and want to refactor? Is it going to be a lot of work to refactor and are they just going to inject what they need into an evolving system of glue code? If I have to call it n times, how can I pass in and reuse memory to avoid memory penalties? What happens to names when we have to reuse symbols? Edit: probably not obvious, but you can probably elegantly describe what you’d do with ideal inputs, but getting those inputs is the particularly hard part.
deleted 5y ago
[deleted]
akkartik 5y ago
That's pretty funny, thanks for the feedback on my style. More on my worldview regarding readability: http://akkartik.name/post/readable-bad http://akkartik.name/post/readable-bad In particular: "In practice, a series of locally well-chosen names gradually end up in overall cacophony. A program with a small harmonious vocabulary of names consistently used is hugely effective regardless of whether its types and variables are visibly distinguished. To put it another way, the readability of a program can be hugely enhanced by the names it doesn't use." You'll probably not like Smalltalk programs either, which almost entirely have names like `aString`. These days I don't get hung up on style. Everyone has their own style, and that's good. When I read a program that does something useful to me, I try to adopt its style.
- mst 5y ago
  I think that people who've been repeatedly exposed to C code written by people who gave everything not particularly well chosen one-letter names end up allergic to them just in general. Given in this specific case the reader (of the article rather than the comment you're replying to) already has the context that it's an interpreter implementation, the meaning of run() was immediately obvious to me, but if I'd missed that sentence in the article I suspect I'd've reacted rather differently.
  - akkartik 5y ago
    One theme of this post -- and my site in general -- is that blog posts are a poor use case to optimize code for. I'd love for you to `git clone` the repo mentioned here and try reading it with your usual editor and so on. That's the habitat my code is really intended for.
    - mst 5y ago
      I have the wart repo cloned into ~/tmp now and am quite fascinated at my first look but haven't dug into it enough to form any actual opinions. I might remember to email you later but if there's somewhere on IRC you're usually connected to telling me where that is will significantly increase the odds of my actually getting around to providing feedback if you'd like that.

by buster 5y ago

engmgrmgr 5y ago

Effort to refactor is something to consider, and verbosity makes this harder as you get lower level. Another thing to consider is the very verbose names can be something that people actively avoid for clean code, and you could end up with spaghetti code to make it both readable and verbose (imagine someone doing this for years and then handing the code off to someone when they leave because they were so pigeonholed in that system that no one else could easily collaborate). Downstream, you can end up with tech debt instead of optimally refactored code as people struggle to do something of a smaller scope. And if every tiny thing is unit tested, it gets even harder to change without expanding the scope of work. Math code is an extreme example of where verbosity can quickly become detrimental.

lionkor 5y ago
Definitely have to disagree. "Clean" code is often an excuse for lazy, short names which need a comment to explain them. Consider this completely fabricated example: // calculates the area of a rectangle with sides a and b, u being true for metric, false for imperial int rarea(int a, int b, bool u); versus int rectangle_area(int side_a, int side_b, bool metric); which more or less doesnt even need a comment anymore. "Clean code" people want short names, massive comments that can be collapsed, so that from really far away, it looks neat. Its a terrible beginner mistake I see time and time again, and it shouldnt be defended. If you write a math formula, how is writing "side_a" or "phi" worse than "a" and "p"?
- dottedmag 5y ago
 `bool metric` does not ring any bells (I never lived in US, so I had to refer to the comment to understand it), and units of `a` and `b` and result are missing.
 - mst 5y ago
 I'd imagine in an ideal world they'd've gone with `enum(Metric, Imperial) units` but as a direct rewrite of the original function signature it was probably the least worst available option.
 - lionkor 5y ago
 `bool metric` implies that `metric` can be YES or NO, that's clearer than what was there before. Its a made-up example, this discussion is about style, not about semantics. To please those who would like to see a semantically improved version: (C++) enum class Unit { Meter, Inch, Foot, // ... }; template<Unit U> struct UnitValue { double value; }; template<Unit U> UnitValue rectangle_area(UnitValue side_a, UnitValue side_b); // invocation example constexpr Unit unit = Unit::Meter; UnitValue<unit> result = rectangle_area<unit>({5.3}, {1.5}); std::cout << result.value << std::endl; There is still room for improvement, maybe some concepts to further generify it, some more comments, maybe a PDF with full documentation, ...
- engmgrmgr 5y ago
 Why would it be worse? Why would you write p instead of phi? I would, however, point out that to call this function, you need to separately compute lengths of sides. Where do those come from? How are coordinates stored? How are you wiring all this up? What happens when you change the data to support more dimensions, or to use memory pools, or to add new shapes? To be clear, a lot of math needs a ton of complex code, and you also often have algorithms optimized for performance, approximation, numerical stability, etc. You can encode your understanding of what’s going on in the naming and break it into chunks so it’s readable, but that’s not necessarily a good thing. Write some code to compute the intersecting earth-surface geometry of the projected frustum far planes from two satellites’ cameras at some point in time. Who’s using this code, is it a library? How do you abstract it? Who are the consumers of the code, will they ever change it or only use a part of it and want to refactor? Is it going to be a lot of work to refactor and are they just going to inject what they need into an evolving system of glue code? If I have to call it n times, how can I pass in and reuse memory to avoid memory penalties? What happens to names when we have to reuse symbols? Edit: probably not obvious, but you can probably elegantly describe what you’d do with ideal inputs, but getting those inputs is the particularly hard part.

deleted 5y ago

[deleted]

akkartik 5y ago

That's pretty funny, thanks for the feedback on my style. More on my worldview regarding readability: http://akkartik.name/post/readable-bad http://akkartik.name/post/readable-bad In particular: "In practice, a series of locally well-chosen names gradually end up in overall cacophony. A program with a small harmonious vocabulary of names consistently used is hugely effective regardless of whether its types and variables are visibly distinguished. To put it another way, the readability of a program can be hugely enhanced by the names it doesn't use." You'll probably not like Smalltalk programs either, which almost entirely have names like `aString`. These days I don't get hung up on style. Everyone has their own style, and that's good. When I read a program that does something useful to me, I try to adopt its style.

mst 5y ago
I think that people who've been repeatedly exposed to C code written by people who gave everything not particularly well chosen one-letter names end up allergic to them just in general. Given in this specific case the reader (of the article rather than the comment you're replying to) already has the context that it's an interpreter implementation, the meaning of run() was immediately obvious to me, but if I'd missed that sentence in the article I suspect I'd've reacted rather differently.
- akkartik 5y ago
  One theme of this post -- and my site in general -- is that blog posts are a poor use case to optimize code for. I'd love for you to `git clone` the repo mentioned here and try reading it with your usual editor and so on. That's the habitat my code is really intended for.
  - mst 5y ago
    I have the wart repo cloned into ~/tmp now and am quite fascinated at my first look but haven't dug into it enough to form any actual opinions. I might remember to email you later but if there's somewhere on IRC you're usually connected to telling me where that is will significantly increase the odds of my actually getting around to providing feedback if you'd like that.