11 ms·

After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment. Then all of a sudden, you don't ne

After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment. Then all of a sudden, you don't need to waste time on careful and deliberate analysis, and hunting down people who might know about it, and making assumptions, because the 2 minutes it would take to write a few lines of explanation would save you all of that. At which point, the real question is: why did they choose not to document this non-obvious solution, and the edge case that required it?

davidw 14y ago
Comments, and, one would hope, some tests showing how the obscure edge case interacts with everything else.
- tedunangst 14y ago
  Sometimes you don't know what the edge cases are because you don't know what the everything else is. If you return something sorted, somebody will write a consumer that depends on the sorting. If you change backends and return things in a different order, you've broken their code. Sure, their code was broken from the start, but it used to work, now it doesn't, and you're the guy who changed something. The only way to prevent this, randomly sorting every unsorted collection you export, isn't feasible to reliably maintain.
  - eru 14y ago
    > The only way to prevent this, randomly sorting every unsorted collection you export, isn't feasible to reliably maintain. It's feasible to maintain. But people might rely on it, too. As a random example (and easily avoidable example), quicksort works with random input, but 'breaks' for pre-sorted input.
    - dpark 14y ago
      That depends on the pivot chosen. If your quicksort implementation actually hits n^2 behavior with sorted input, it's probably not the best implementation. Any implementation can hit n^2 with random input. It's just highly unlikely.
      - eru 14y ago
        Yes, I know. That's what the "easily avoidable" was for. I couldn't think of a better example in a few minutes, but if something can go wrong, I am sure it will eventually go wrong.
kaib 14y ago
I've come across a lot of code where the code itself was the clearest way to communicate the subtlety inherent in it. I think you have an inflated expectation of what human languages can document in a reasonable space. Many times it will take months to understand the edge case even if you have a human trying to describe it to you directly, let alone by reading a non-interactive comment.
- gjm11 14y ago
  The code may well be the clearest way to communicate the subtlety. That doesn't mean a comment isn't helpful to communicate that there's subtlety there and give some idea of what sort of case it's meant to be about. // It may look as if you could just say p->adjust() here, // but that doesn't work because of a subtlety involving // cancelled credit cards belonging to purchasers in Uganda. // Please tread carefully! ... And then, if talking to another human being is the only real way to grasp what's going on, you use your version control system to find out who added that comment and go talk to them.
- alistair77 14y ago
  In these cases a simple, "Function is required to handle multiple edge cases", comment would at least alert other developers to a reason for ostensibly odd or overly complex code. This along with well commented test cases solves most issues.
- biot 14y ago
  You'll run into problems as soon as it's not the code that's left which explains the subtlely, but the code that you had to remove. In such cases, a comment explaining (for example) why the obvious choice of library FooBar was abandoned for a more direct-metal approach would provide the answer to the code which isn't there.
- FuzzyDunlop 14y ago
  But you might not even need to understand the edge case, you just need to know that it's there, and it means the code is more complex than it really should be. The code itself cannot reasonably communicate the developer's true intent, and so a short comment can remove any ambiguity even if it doesn't explain the issue in full. The GP assumed incompetence, when it was really pragmatism.
CodeMage 14y ago
At which point, the real question is: why did they choose not to document this non-obvious solution, and the edge case that required it? From my personal experience with "corporate programming", the usual suspects are: 1) corporate culture that dictates that you need to get the code out ASAP and let someone else worry about maintenance 2) original author's assumption that he/she will be the only one to touch that code I've been guilty of #2 before I learned that even if I am the only one to touch the code, if I wait long enough before I come back to it, I'll still have the same problem as a newcomer would. As for #1, this is a typical corporate culture for any company whose business isn't producing code (and for quite a few whose business is precisely that).
- nathan_long 14y ago
  1) corporate culture that dictates that you need to get the code out ASAP and let someone else worry about maintenance Unfortunately, three months from now, "someone else" is you, and "getting the code out ASAP" means figuring out the spaghetti code you wrote but no longer understand. In the long run, doing it right the first time helps us go faster. Therefore, it's part of the programmer's job to resist pressure to do it wrong.
- vidarh 14y ago
  3) The code was indeed obvious for the people who had worked on the project for a while. When you get familiar with a domain it is very easy to get blind to what people without exposure to it will consider obvious or not.
- pasbesoin 14y ago
  3) A culture that thinks/mandates that "unnecessary comments" "clutter" the code. 4) Documentation that is held separate / made in different systems. That diverge over time. Or, one failure in training of the new guy is to not provide them a good overview of the documentation system(s). And/Or, the documentation organization and systems are cumbersome to the point of being unuseful, unless you already have a pretty good idea of where stuff is (and isn't -- all those empty forms that end up being ignored).
  - 14y ago
huggyface 14y ago
After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment. If the code isn't the clearest comment you have, you're doing it wrong. Comments are a crutch for people who write poor code. Comments have zero authority or guarantee of accuracy, and more often than not have little correlation with the actual code. Code is canonical. Comments are noise.
- eru 14y ago
  Mathematicians have much more convenient symbols and powerful notation than programmers. Yet they use text, too. Even wondered why? Donald Knuth, who gives money to people who spot bugs in his code, even invented literate programming to mix prose explanation and code better. Is he an idiot?
  - huggyface 14y ago
    I'll happily be "so brave" and reiterate a simple truism of software development -- comments are the battle cry of terrible developers. They are the crutch of people who can't read code: "Add more comments because otherwise I can't make sense of what the statements are doing." It is the English speaker demanding that every French passage have an English translation, rather than simply learning French. They are the crutch of people who can't write code. "My code is a gigantic, illiterate mess, so instead read the comment at the top that has no guarantee of being robust or accurate." Bringing up mathematicians and Knuth are both irrelevant distractions. Software development in the modern world is a very structure, self-describing affair, or at least it should be. Comments are the short-circuit from having to figure out how to do that.
    - ballooney 14y ago
      Your hubris is certainly self-documenting, if it gives you any comfort.
      - ChuckMcM 14y ago
        He (or she) is just early on the path, and like a newborn kitten their eyes are still closed. In the mean time keep them away from pointy things.
nathan_long 14y ago
Agreed, with one caveat: even better than explanatory comments are explanatory method and variable names, when possible. For example, you could have one 10-line method, interspersed with comments, or you could have a hierarchy of method calls, each with a name so clear that it needs no comments. The second method is less likely to get out of sync with what the code actually does, and it's more testable. This the lesson that stuck with me most from Clean Code, which I highly recommend.
- wikwocket 14y ago
  Even better is naming things as intuitively as possible, and to use explanatory comments where they would be helpful. Not trying to pick on you, but every time I see someone implying that "naming things better" is a panacea, I want to throw it out there that sometimes, nothing beats a good comment to explain (in natural language) what's going on here.
  - nathan_long 14y ago
    We're on the same page. Generally, I find that naming things better helps explain what the program is doing, and comments help explain why. And comments will stand out best if they are only used when needed to answer the question "why didn't they just..." :)

davidw 14y ago

Comments, and, one would hope, some tests showing how the obscure edge case interacts with everything else.

tedunangst 14y ago
Sometimes you don't know what the edge cases are because you don't know what the everything else is. If you return something sorted, somebody will write a consumer that depends on the sorting. If you change backends and return things in a different order, you've broken their code. Sure, their code was broken from the start, but it used to work, now it doesn't, and you're the guy who changed something. The only way to prevent this, randomly sorting every unsorted collection you export, isn't feasible to reliably maintain.
- eru 14y ago
  > The only way to prevent this, randomly sorting every unsorted collection you export, isn't feasible to reliably maintain. It's feasible to maintain. But people might rely on it, too. As a random example (and easily avoidable example), quicksort works with random input, but 'breaks' for pre-sorted input.
  - dpark 14y ago
    That depends on the pivot chosen. If your quicksort implementation actually hits n^2 behavior with sorted input, it's probably not the best implementation. Any implementation can hit n^2 with random input. It's just highly unlikely.
    - eru 14y ago
      Yes, I know. That's what the "easily avoidable" was for. I couldn't think of a better example in a few minutes, but if something can go wrong, I am sure it will eventually go wrong.

kaib 14y ago

I've come across a lot of code where the code itself was the clearest way to communicate the subtlety inherent in it. I think you have an inflated expectation of what human languages can document in a reasonable space. Many times it will take months to understand the edge case even if you have a human trying to describe it to you directly, let alone by reading a non-interactive comment.

gjm11 14y ago
The code may well be the clearest way to communicate the subtlety. That doesn't mean a comment isn't helpful to communicate that there's subtlety there and give some idea of what sort of case it's meant to be about. // It may look as if you could just say p->adjust() here, // but that doesn't work because of a subtlety involving // cancelled credit cards belonging to purchasers in Uganda. // Please tread carefully! ... And then, if talking to another human being is the only real way to grasp what's going on, you use your version control system to find out who added that comment and go talk to them.
alistair77 14y ago
In these cases a simple, "Function is required to handle multiple edge cases", comment would at least alert other developers to a reason for ostensibly odd or overly complex code. This along with well commented test cases solves most issues.
biot 14y ago
You'll run into problems as soon as it's not the code that's left which explains the subtlely, but the code that you had to remove. In such cases, a comment explaining (for example) why the obvious choice of library FooBar was abandoned for a more direct-metal approach would provide the answer to the code which isn't there.
FuzzyDunlop 14y ago
But you might not even need to understand the edge case, you just need to know that it's there, and it means the code is more complex than it really should be. The code itself cannot reasonably communicate the developer's true intent, and so a short comment can remove any ambiguity even if it doesn't explain the issue in full. The GP assumed incompetence, when it was really pragmatism.

CodeMage 14y ago

At which point, the real question is: why did they choose not to document this non-obvious solution, and the edge case that required it? From my personal experience with "corporate programming", the usual suspects are: 1) corporate culture that dictates that you need to get the code out ASAP and let someone else worry about maintenance 2) original author's assumption that he/she will be the only one to touch that code I've been guilty of #2 before I learned that even if I am the only one to touch the code, if I wait long enough before I come back to it, I'll still have the same problem as a newcomer would. As for #1, this is a typical corporate culture for any company whose business isn't producing code (and for quite a few whose business is precisely that).

nathan_long 14y ago
1) corporate culture that dictates that you need to get the code out ASAP and let someone else worry about maintenance Unfortunately, three months from now, "someone else" is you, and "getting the code out ASAP" means figuring out the spaghetti code you wrote but no longer understand. In the long run, doing it right the first time helps us go faster. Therefore, it's part of the programmer's job to resist pressure to do it wrong.
vidarh 14y ago
3) The code was indeed obvious for the people who had worked on the project for a while. When you get familiar with a domain it is very easy to get blind to what people without exposure to it will consider obvious or not.
pasbesoin 14y ago
3) A culture that thinks/mandates that "unnecessary comments" "clutter" the code. 4) Documentation that is held separate / made in different systems. That diverge over time. Or, one failure in training of the new guy is to not provide them a good overview of the documentation system(s). And/Or, the documentation organization and systems are cumbersome to the point of being unuseful, unless you already have a pretty good idea of where stuff is (and isn't -- all those empty forms that end up being ignored).
- 14y ago

huggyface 14y ago

After the recent discussion about code-comments, that sort of code is exactly the sort that requires an explanatory comment. If the code isn't the clearest comment you have, you're doing it wrong. Comments are a crutch for people who write poor code. Comments have zero authority or guarantee of accuracy, and more often than not have little correlation with the actual code. Code is canonical. Comments are noise.

eru 14y ago
Mathematicians have much more convenient symbols and powerful notation than programmers. Yet they use text, too. Even wondered why? Donald Knuth, who gives money to people who spot bugs in his code, even invented literate programming to mix prose explanation and code better. Is he an idiot?
- huggyface 14y ago
  I'll happily be "so brave" and reiterate a simple truism of software development -- comments are the battle cry of terrible developers. They are the crutch of people who can't read code: "Add more comments because otherwise I can't make sense of what the statements are doing." It is the English speaker demanding that every French passage have an English translation, rather than simply learning French. They are the crutch of people who can't write code. "My code is a gigantic, illiterate mess, so instead read the comment at the top that has no guarantee of being robust or accurate." Bringing up mathematicians and Knuth are both irrelevant distractions. Software development in the modern world is a very structure, self-describing affair, or at least it should be. Comments are the short-circuit from having to figure out how to do that.
  - ballooney 14y ago
    Your hubris is certainly self-documenting, if it gives you any comfort.
    - ChuckMcM 14y ago
      He (or she) is just early on the path, and like a newborn kitten their eyes are still closed. In the mean time keep them away from pointy things.

nathan_long 14y ago

Agreed, with one caveat: even better than explanatory comments are explanatory method and variable names, when possible. For example, you could have one 10-line method, interspersed with comments, or you could have a hierarchy of method calls, each with a name so clear that it needs no comments. The second method is less likely to get out of sync with what the code actually does, and it's more testable. This the lesson that stuck with me most from Clean Code, which I highly recommend.

wikwocket 14y ago
Even better is naming things as intuitively as possible, and to use explanatory comments where they would be helpful. Not trying to pick on you, but every time I see someone implying that "naming things better" is a panacea, I want to throw it out there that sometimes, nothing beats a good comment to explain (in natural language) what's going on here.
- nathan_long 14y ago
  We're on the same page. Generally, I find that naming things better helps explain what the program is doing, and comments help explain why. And comments will stand out best if they are only used when needed to answer the question "why didn't they just..." :)