7 ms·

Agree with most of what you said, except on the impossible part. You can tell everything with code, given enough time and resources. Nothing is "impossible

by otikik 4y ago

Agree with most of what you said, except on the __impossible__ part. You can tell everything with code, given enough time and resources. Nothing is "impossible". But there's a point where you hit diminishing returns. It's about efficiency. Other devs, or your future self, will have to time trying to build the same "castle in your head" as you did. Can a comment shorten that time? If a one-line comment saves 15 minutes of investigation in aggregate, that's a no-brainer. You should add it. Conversely, a line that says "add 5 to x" is just wasting everyone's time. As a general rule, once I have finally understood a particularly hairy piece of code, I don't want to do it again in 6 months. I have even done ASCII diagrams in the comments explaining how a particularly hairy piece of code worked, when I hated it enough.

jofer 4y ago
ASCII diagram comments are surprisingly common in scientific computing, FWIW. It's not so much that it's always hairy code, more that it helps to add some visualizations of what's going on. Math vs intuitive understanding are often very different things. It's something I wish was more common than it is. Sometimes you really want that ASCII pseudo graph explaining how minimizing this thing relates to that other thing that we actually care about. Taken a step further, I really wish we had better systems for managing this type of information alongside a codebase. E.g. the whitepaper, or presentation, or figures, or whatever is often very necessary to understand the code, and ideally it would be under version control and live neatly alongside things. Nicely rendered docs definitely help with this (e.g. latex in comments), but I'm always surprised there aren't more people focusing on this aspect of information management.
lumb63 4y ago
In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams. I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.
- layer8 4y ago
  What I would miss, in the above, is information about: - where the page is being read from - what page numbers the function accepts - what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact) - other possible error conditions, if any (I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)
still_grokking 4y ago
> You can tell everything with code, given enough time and resources. That's just not true. There are infinite many ways to write the exact same thing. Your code can never say why it's like it is, why this approach was chosen and not another. > […] the comments explaining how a particularly hairy piece of code worked […] This kind of comments are the bad ones actually. Your code should be clear enough that it's easy to see how it works and what is happening. The rule is actually very simple, and I don't get it why so many people have issues with following it. "Code says what and how, comments say why."
- TedDoesntTalk 4y ago
  > The rule is actually very simple Why does there have to be rules about when to comment? I comment frequently about whatever the hell I want. Don’t like it? Then don’t read the comments. Very simple, just like your rule.
  - still_grokking 4y ago
    Useless comments are like useless code: They create an unnecessary (and therefore costly) maintenance burden. If you think you're the smartest person on the planet so "rules" (or better said best practices) don't apply to anything you do I hope nobody ever needs to collaborate with you. All the "rules" are there for a reason! No, you're not free do to whatever you like in a professional setting. For example when you're operating machines you need to follow safety regulations. Otherwise you could even end up in jail quite quickly.
    - TedDoesntTalk 4y ago
      > All the "rules" are there for a reason! Except in this case, you've made up the rule. It is not an axiomatic rule like gravity. I want different rules. So unless we work together, your rules don't apply to me.
- otikik 4y ago
  > There are infinite many ways to write the exact same thing. I agree with that. I don't think that makes things impossible. Only more difficult. > Your code can never say why it's like it is, why this approach was chosen and not another. If the why is important, given enough time and resources, someone will eventually complain that something is not working and someone will be tasked to "fix it". It may take them weeks, but they will eventually figure out the why. > Code says what and how, comments say why. If we are considering only quality vs quality, I agree. But there's also quantity. When the how is complicated enough, it is indistinguishable from a why. You will hear the reviewers ask outloud: "But WHY is this done this way?". Even if the problem is merely algorithmic/technical and the code is doing exactly what it's supposed to do. Then you have two options: spend a potentially significant time refactoring things (which is always the right choice, given enough time and resources) or spend 10 minutes writing a comment with what you learned, and moving on to the next problem.

Agree with most of what you said, except on the __impossible__ part. You can tell everything with code, given enough time and resources. Nothing is "impossible

by otikik 4y ago

jofer 4y ago

ASCII diagram comments are surprisingly common in scientific computing, FWIW. It's not so much that it's always hairy code, more that it helps to add some visualizations of what's going on. Math vs intuitive understanding are often very different things. It's something I wish was more common than it is. Sometimes you really want that ASCII pseudo graph explaining how minimizing this thing relates to that other thing that we actually care about. Taken a step further, I really wish we had better systems for managing this type of information alongside a codebase. E.g. the whitepaper, or presentation, or figures, or whatever is often very necessary to understand the code, and ideally it would be under version control and live neatly alongside things. Nicely rendered docs definitely help with this (e.g. latex in comments), but I'm always surprised there aren't more people focusing on this aspect of information management.

lumb63 4y ago

In my experience, one man’s “waste of time” is another man’s castle-in-the-head-building-time-saver. At my current company, if I have reasonable, self explanatory code, such as a function with the signature “read_page(page_num: u32) -> PageData”, they’ll gather it reads a page with the given page number and extracts the data. At my last company, if I wrote the same code, I’d receive a comment on my PR complaining I did not document it will enough. I would then add a comment that somehow only I was able to detect was snarkily written, something like “// reads the given page number and returns its data” and they would be happy as clams. I always assumed that behavior was dogmatic until, over many PRs, multiple members of the team commented that if I commented my code, it would be much easier to read. And comments of the above quality assuaged them.

layer8 4y ago
What I would miss, in the above, is information about: - where the page is being read from - what page numbers the function accepts - what happens if an invalid page number is specified (or if that’s deliberately undefined, stating that fact) - other possible error conditions, if any (I’ll assume that PageData already documents what “page” refers to in that context, because for me it’s not “self explanatory” just from the function signature you provided.)

still_grokking 4y ago

> You can tell everything with code, given enough time and resources. That's just not true. There are infinite many ways to write the exact same thing. Your code can never say why it's like it is, why this approach was chosen and not another. > […] the comments explaining how a particularly hairy piece of code worked […] This kind of comments are the bad ones actually. Your code should be clear enough that it's easy to see how it works and what is happening. The rule is actually very simple, and I don't get it why so many people have issues with following it. "Code says what and how, comments say why."

TedDoesntTalk 4y ago
> The rule is actually very simple Why does there have to be rules about when to comment? I comment frequently about whatever the hell I want. Don’t like it? Then don’t read the comments. Very simple, just like your rule.
- still_grokking 4y ago
  Useless comments are like useless code: They create an unnecessary (and therefore costly) maintenance burden. If you think you're the smartest person on the planet so "rules" (or better said best practices) don't apply to anything you do I hope nobody ever needs to collaborate with you. All the "rules" are there for a reason! No, you're not free do to whatever you like in a professional setting. For example when you're operating machines you need to follow safety regulations. Otherwise you could even end up in jail quite quickly.
  - TedDoesntTalk 4y ago
    > All the "rules" are there for a reason! Except in this case, you've made up the rule. It is not an axiomatic rule like gravity. I want different rules. So unless we work together, your rules don't apply to me.
otikik 4y ago
> There are infinite many ways to write the exact same thing. I agree with that. I don't think that makes things impossible. Only more difficult. > Your code can never say why it's like it is, why this approach was chosen and not another. If the why is important, given enough time and resources, someone will eventually complain that something is not working and someone will be tasked to "fix it". It may take them weeks, but they will eventually figure out the why. > Code says what and how, comments say why. If we are considering only quality vs quality, I agree. But there's also quantity. When the how is complicated enough, it is indistinguishable from a why. You will hear the reviewers ask outloud: "But WHY is this done this way?". Even if the problem is merely algorithmic/technical and the code is doing exactly what it's supposed to do. Then you have two options: spend a potentially significant time refactoring things (which is always the right choice, given enough time and resources) or spend 10 minutes writing a comment with what you learned, and moving on to the next problem.