4 ms·

> for another developer (who may not exist) You, 6 months from now (or whenever you stop touching this code base), are effectively "another developer". New de

> for another developer (who may not exist) You, 6 months from now (or whenever you stop touching this code base), are effectively "another developer". New developers don't seem to really grasp this until the first time they have to maintain their own old code. I don't think it really hits home until the first time you experience: "What is this? Who wrote this garbage??" runs git blame "..oh, crap."

milkytron 9y ago
This is why I usually throw in comments with myself as the recipient for understanding where complexity exists. I've heard people debate over whether comments should be in well written code, including some that argued comments should never be used at all. Party A: Code should be easily understandable so that comments aren't necessary. Party B: Comments should exist where complexity exists to save a developer's time when determining what is and is not important to them. Sometimes though, you just can't avoid it. The few times I had to write PERL are prime examples.
- humanrebar 9y ago
  Generally the best comments are to describe "why" (sometimes "how") more than "what". Of course, good writers know their audience. If that code is somehow strange in its organizational context, a few "what" comments and links to references, documentation, and/or tutorials can be great.
- gregmac 9y ago
  Obviously the worst comments are utterly obvious: // Get the users name name = get name(); There are lots of cases where inline comments are very useful though. As an example, most of my team isn't strong on regular expressions, so when I use one, I'll usually put a comment explaining what it does in slightly more detail than I normally might (to the point it would be a bit too rudimentary to anyone well versed in regex). I've also been writing lots of automation scripts for stuff running at AWS lately, which often involves using strange AWS CLI filter syntax, jq expressions (for JSON parsing) and some other random utilities like sed, cut, sort, etc. Even for myself, I put fairly detailed comments, but I don't use those on a regular basis and usage isn't always obvious anyway.
  - flukus 9y ago
    Regular expressions are the perfect use case for unit tests, they are simple input/output pure functions. Not only do you ensure that they work, you provide several examples to future devs of what should and should not be considered a match. On the automation scripts I really need to take a leaf out of your book though, I'm awfully undisciplined at commenting them and it always comes back to bite me.
    - gregmac 9y ago
      100% agree on unit testing regex, but spending a minute to type a detailed comment that saves sometime the extra time of navigating to and reading several unit test cases is worth it. If someone is modifying the regex the tests are essential, but for someone just reading the code why not save them the time?
  - daemin 9y ago
    Actually I would consider that a decent comment, since get_name() doesn't actually say what name it is getting. It could have been some other name in the system. This would depend on the context and the surrounding code though.
- lmm 9y ago
  It's analogous to a translation note: any time you need to add a comment is a time where you've failed as a programmer. Sometimes it's necessary, but it should be a last resort. I can well believe that writing Perl would require comments, but to my mind that's a case of "don't do that then".

milkytron 9y ago

This is why I usually throw in comments with myself as the recipient for understanding where complexity exists. I've heard people debate over whether comments should be in well written code, including some that argued comments should never be used at all. Party A: Code should be easily understandable so that comments aren't necessary. Party B: Comments should exist where complexity exists to save a developer's time when determining what is and is not important to them. Sometimes though, you just can't avoid it. The few times I had to write PERL are prime examples.

humanrebar 9y ago
Generally the best comments are to describe "why" (sometimes "how") more than "what". Of course, good writers know their audience. If that code is somehow strange in its organizational context, a few "what" comments and links to references, documentation, and/or tutorials can be great.
gregmac 9y ago
Obviously the worst comments are utterly obvious: // Get the users name name = get name(); There are lots of cases where inline comments are very useful though. As an example, most of my team isn't strong on regular expressions, so when I use one, I'll usually put a comment explaining what it does in slightly more detail than I normally might (to the point it would be a bit too rudimentary to anyone well versed in regex). I've also been writing lots of automation scripts for stuff running at AWS lately, which often involves using strange AWS CLI filter syntax, jq expressions (for JSON parsing) and some other random utilities like sed, cut, sort, etc. Even for myself, I put fairly detailed comments, but I don't use those on a regular basis and usage isn't always obvious anyway.
- flukus 9y ago
  Regular expressions are the perfect use case for unit tests, they are simple input/output pure functions. Not only do you ensure that they work, you provide several examples to future devs of what should and should not be considered a match. On the automation scripts I really need to take a leaf out of your book though, I'm awfully undisciplined at commenting them and it always comes back to bite me.
  - gregmac 9y ago
    100% agree on unit testing regex, but spending a minute to type a detailed comment that saves sometime the extra time of navigating to and reading several unit test cases is worth it. If someone is modifying the regex the tests are essential, but for someone just reading the code why not save them the time?
- daemin 9y ago
  Actually I would consider that a decent comment, since get_name() doesn't actually say what name it is getting. It could have been some other name in the system. This would depend on the context and the surrounding code though.
lmm 9y ago
It's analogous to a translation note: any time you need to add a comment is a time where you've failed as a programmer. Sometimes it's necessary, but it should be a last resort. I can well believe that writing Perl would require comments, but to my mind that's a case of "don't do that then".