Hacker News Reader

Comment by kaib | Hacker News Reader

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.

View on HN

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.

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.

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.

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.

Reply on news.ycombinator.com