28 ms·

Why must that documentation go inline with the code? There are so many better ways to document design and implementation decisions that don't involve embedding

Why must that documentation go inline with the code? There are so many better ways to document design and implementation decisions that don't involve embedding English into source code files. We preach endlessly the idea of orthogonality and abstraction, but then we smash together plain English and Python/C++/Erlang/whatever?

simonbarker87 4y ago
If the information in the comment directly relates to the code and is for developers then putting it next to the code makes a lot of sense. Putting it somewhere else just increases the likelihood it will go stale and decreases discoverability of the information.
- SpeedilyDamage 4y ago
  But that's the point; if it's a "why" doc, it shouldn't be specific to the code, so by virtue of the fact that you feel the need to place it there anyway, it's not really a "why" doc at all, and instead should be resolved by writing clearer code. We agree code should be split into multiple files, why do we suddenly not agree that English should be split as well? Nobody would try to write a file with 30% JS, 50% C++, and 20% Python.
  - alpaca128 4y ago
    Code is very formal and limited in what it can express. The real world tends to be much more chaotic. It is impossible by definition to express some reasons just in code, that's why comments are sometimes necessary. > if it's a "why" doc, it shouldn't be specific to the code Sometimes the "why" is directly connected to that specific part of the code and doesn't concern anything else, or anyone not working on that part of the code. Separating & moving the explanation to another place just makes it less visible exactly where it matters.
    - SpeedilyDamage 4y ago
      If the explanation is directly connected to specific parts of the code, it's not "why", it's "how". "Why" will be true regardless of implementation, "how" won't be. Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code. Put the comments elsewhere. We don't put all our code in one file to solve "it needs to be visible!" problems, we shouldn't do it with our docs either, it is not consistent nor is it helpful.
      - kmoser 4y ago
        You're treating comments like a pariah because they might be wrong (i.e. not accurately describe what the code is doing) but that's just as true for the code itself: it may not be doing what it is actually intended to do. In fact, there may be cases where the comment is correct (i.e. it describes what the code should do) but the code is wrong and doesn't actually do it correctly. Why should the comments take a back seat in that case? In reality, comments and code are part of the whole system. There's nothing wrong with being suspicious of a comment's accuracy, but that doesn't mean comments aren't helpful. Part of development is keeping code and comments in sync. Yes, programming is hard.
        SpeedilyDamage 4y ago
        This is a bad take, as the code is actually executed, whereas comments are not. As the code is, definitionally, the way the program works, it must be correct, necessarily. This is not true of the comments. This is why comments are dangerous and bad, only to be used when you've run out of time and/or aren't smart enough to figure a problem out (happens to everyone).
        kmoser 4y ago
        I respectfully disagree with your assertion that because the code is how the program works, it is by definition correct. Wouldn't you define a bug as incorrect code? In any case, even if the code is perfectly correct, comments can and should be used to describe why certain decisions were made, when they are not otherwise obvious from looking at the code. E.g. "You might think a bitfield would be more efficient for storing this data but we choose an array of long ints because in the near future we plan to update the code to pass this as an argument to foo() which assumes an array of long ints." Comments are not limited to instances when you run out of time or are not smart enough to figure out a problem. The whole idea of comments is to save a future developer from the headache of figuring out the things you're writing comments about.
tstrimple 4y ago
While I'm not a fan of excessive comments in code, I am a firm believer in keeping project documentation next to the project. I can't tell you how many places I've been where project documentation was spread across OneNote, Confluence, documents in SharePoint, etc, etc, etc. Any project I have this sort of control over will have the documentation for the project in the repo. I find having a git history of your documentation that can be viewed alongside the history for your code adds so much value to the documentation.
- SpeedilyDamage 4y ago
  Sure, but throw it in a README.md, not in the code itself. Besides, if you foster a culture of writing "why" docs, the problem of where to place these docs is one you solved early on, so people will know where to go.
  - tstrimple 4y ago
    Absolutely. If you were to survey, I would fall much more closely on the "don't comment code" side of things. But if you have documentation for your project, keep it close to the project. That's all.
Supermancho 4y ago
> Why must that documentation go inline with the code? Discoverability and context would not be nearly as useful, to start. Why you need to ask the question, as if there is no suitable answer, is suspect of a thoughtless conclusion. In the late 80s, there was an idea floated that every file could have a sister file with comments, such that they would not need to be parsed/discarded by a parser. This would aid in generating documentation, among other tooling. When I was starting out, I expected this to take hold, but it never did. > There are so many better ways to document design and implementation decisions that don't involve embedding English into source code files I don't think that's been demonstrated.
- midoridensha 4y ago
  >In the late 80s, there was an idea floated that every file could have a sister file with comments, such that they would not need to be parsed/discarded by a parser. This would aid in generating documentation, among other tooling. This sounds a lot like the director's commentary tracks on DVDs. No one ever watched those, and the sister-comment-file would flop the same way if anyone really tried it. A separate file is fine for documenting overall design, but for detailing sections of code, the commentary needs to be close to it, where people will see it.
  - Supermancho 4y ago
    > No one ever watched those, and the sister-comment-file would flop the same way if anyone really tried it Not if it was integrated with an IDE such that you could expand it shrug
baby 4y ago
Imo you should do both. Comments + external doc.
- SpeedilyDamage 4y ago
  You should not, as comments intermingled with code is a distraction at best, and actively harmful at worst.
  - baby 4y ago
    You know, I find your point of view insane and crazy, but I’m willing to consider that some people really see code as a different language like let’s say Chinese and would find it crazy to mix english and chinese together. I don’t see any other explanation
    - SpeedilyDamage 4y ago
      It's probably worth examining why you think my PoV is "insane and crazy" as that's not a normal reaction.
      - devonbleak 4y ago
        Comments intermingled with code help me navigate as I'm trying to accomplish my task. A simple comment every "paragraph" of code or so helps me narrow down the amount of code I need to mentally parse to get to the part that's actually relevant to what I'm trying to do. So since we're supposed to be on the same team, explicitly saying "go fuck yourself, load a mental model of the entire codebase to find the part that's relevant to your task, I'm not going to help you" does indeed seem insane and crazy.
        SpeedilyDamage 4y ago
        I feel like you're missing the entire point of abstraction. When you're looking at code, you should be able to understand what it does by way of how it's structured, and you shouldn't have to load the entire codebase in your brain to do that. You see a function called, "getCustomer" you shouldn't have to dive into that function to understand what you're getting back. It's a customer, no need to figure out how it got the customer or what the format is, etc. Whether or not you realize it, you've gotten to the point of arguing against a lot of really common and proven out design concepts (abstraction layers, orthogonality and the LoD, data types, etc.) without even realizing. "How can I know how the program works without comments unless I load the entire thing into my brain all at once?" is not a question you ask if you understand these principles, because you know you won't need to.

simonbarker87 4y ago

If the information in the comment directly relates to the code and is for developers then putting it next to the code makes a lot of sense. Putting it somewhere else just increases the likelihood it will go stale and decreases discoverability of the information.

SpeedilyDamage 4y ago
But that's the point; if it's a "why" doc, it shouldn't be specific to the code, so by virtue of the fact that you feel the need to place it there anyway, it's not really a "why" doc at all, and instead should be resolved by writing clearer code. We agree code should be split into multiple files, why do we suddenly not agree that English should be split as well? Nobody would try to write a file with 30% JS, 50% C++, and 20% Python.
- alpaca128 4y ago
  Code is very formal and limited in what it can express. The real world tends to be much more chaotic. It is impossible by definition to express some reasons just in code, that's why comments are sometimes necessary. > if it's a "why" doc, it shouldn't be specific to the code Sometimes the "why" is directly connected to that specific part of the code and doesn't concern anything else, or anyone not working on that part of the code. Separating & moving the explanation to another place just makes it less visible exactly where it matters.
  - SpeedilyDamage 4y ago
    If the explanation is directly connected to specific parts of the code, it's not "why", it's "how". "Why" will be true regardless of implementation, "how" won't be. Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code. Put the comments elsewhere. We don't put all our code in one file to solve "it needs to be visible!" problems, we shouldn't do it with our docs either, it is not consistent nor is it helpful.
    - kmoser 4y ago
      You're treating comments like a pariah because they might be wrong (i.e. not accurately describe what the code is doing) but that's just as true for the code itself: it may not be doing what it is actually intended to do. In fact, there may be cases where the comment is correct (i.e. it describes what the code should do) but the code is wrong and doesn't actually do it correctly. Why should the comments take a back seat in that case? In reality, comments and code are part of the whole system. There's nothing wrong with being suspicious of a comment's accuracy, but that doesn't mean comments aren't helpful. Part of development is keeping code and comments in sync. Yes, programming is hard.
      - SpeedilyDamage 4y ago
        This is a bad take, as the code is actually executed, whereas comments are not. As the code is, definitionally, the way the program works, it must be correct, necessarily. This is not true of the comments. This is why comments are dangerous and bad, only to be used when you've run out of time and/or aren't smart enough to figure a problem out (happens to everyone).
        kmoser 4y ago
        I respectfully disagree with your assertion that because the code is how the program works, it is by definition correct. Wouldn't you define a bug as incorrect code? In any case, even if the code is perfectly correct, comments can and should be used to describe why certain decisions were made, when they are not otherwise obvious from looking at the code. E.g. "You might think a bitfield would be more efficient for storing this data but we choose an array of long ints because in the near future we plan to update the code to pass this as an argument to foo() which assumes an array of long ints." Comments are not limited to instances when you run out of time or are not smart enough to figure out a problem. The whole idea of comments is to save a future developer from the headache of figuring out the things you're writing comments about.

tstrimple 4y ago

While I'm not a fan of excessive comments in code, I am a firm believer in keeping project documentation next to the project. I can't tell you how many places I've been where project documentation was spread across OneNote, Confluence, documents in SharePoint, etc, etc, etc. Any project I have this sort of control over will have the documentation for the project in the repo. I find having a git history of your documentation that can be viewed alongside the history for your code adds so much value to the documentation.

SpeedilyDamage 4y ago
Sure, but throw it in a README.md, not in the code itself. Besides, if you foster a culture of writing "why" docs, the problem of where to place these docs is one you solved early on, so people will know where to go.
- tstrimple 4y ago
  Absolutely. If you were to survey, I would fall much more closely on the "don't comment code" side of things. But if you have documentation for your project, keep it close to the project. That's all.

Supermancho 4y ago

> Why must that documentation go inline with the code? Discoverability and context would not be nearly as useful, to start. Why you need to ask the question, as if there is no suitable answer, is suspect of a thoughtless conclusion. In the late 80s, there was an idea floated that every file could have a sister file with comments, such that they would not need to be parsed/discarded by a parser. This would aid in generating documentation, among other tooling. When I was starting out, I expected this to take hold, but it never did. > There are so many better ways to document design and implementation decisions that don't involve embedding English into source code files I don't think that's been demonstrated.

midoridensha 4y ago
>In the late 80s, there was an idea floated that every file could have a sister file with comments, such that they would not need to be parsed/discarded by a parser. This would aid in generating documentation, among other tooling. This sounds a lot like the director's commentary tracks on DVDs. No one ever watched those, and the sister-comment-file would flop the same way if anyone really tried it. A separate file is fine for documenting overall design, but for detailing sections of code, the commentary needs to be close to it, where people will see it.
- Supermancho 4y ago
  > No one ever watched those, and the sister-comment-file would flop the same way if anyone really tried it Not if it was integrated with an IDE such that you could expand it shrug

baby 4y ago

Imo you should do both. Comments + external doc.

SpeedilyDamage 4y ago
You should not, as comments intermingled with code is a distraction at best, and actively harmful at worst.
- baby 4y ago
  You know, I find your point of view insane and crazy, but I’m willing to consider that some people really see code as a different language like let’s say Chinese and would find it crazy to mix english and chinese together. I don’t see any other explanation
  - SpeedilyDamage 4y ago
    It's probably worth examining why you think my PoV is "insane and crazy" as that's not a normal reaction.
    - devonbleak 4y ago
      Comments intermingled with code help me navigate as I'm trying to accomplish my task. A simple comment every "paragraph" of code or so helps me narrow down the amount of code I need to mentally parse to get to the part that's actually relevant to what I'm trying to do. So since we're supposed to be on the same team, explicitly saying "go fuck yourself, load a mental model of the entire codebase to find the part that's relevant to your task, I'm not going to help you" does indeed seem insane and crazy.
      - SpeedilyDamage 4y ago
        I feel like you're missing the entire point of abstraction. When you're looking at code, you should be able to understand what it does by way of how it's structured, and you shouldn't have to load the entire codebase in your brain to do that. You see a function called, "getCustomer" you shouldn't have to dive into that function to understand what you're getting back. It's a customer, no need to figure out how it got the customer or what the format is, etc. Whether or not you realize it, you've gotten to the point of arguing against a lot of really common and proven out design concepts (abstraction layers, orthogonality and the LoD, data types, etc.) without even realizing. "How can I know how the program works without comments unless I load the entire thing into my brain all at once?" is not a question you ask if you understand these principles, because you know you won't need to.