7 ms·

Seems like an appropriate time to share my 4 reasons to leave a code comment: 1. An odd business requirement (share the origin story) 2. It took research (sum

Seems like an appropriate time to share my 4 reasons to leave a code comment: 1. An odd business requirement (share the origin story) 2. It took research (summarize with links) 3. Multiple options were considered (justify decision) 4. Question in a code review (answer in a comment)

spoiler 4y ago
I've not been doing 4, but it's s great idea. If someone's asked the question, it's likely it will come up again for the next person reading the code!
- capableweb 4y ago
  As an aside, my first try is always to try to clarify the code itself if someone has a specific question, so the obvious answer is in the code. But if I'm unable to signal that in code, a comment will do just fine.
  - hakunin 4y ago
    I couldn't fit this part in my tweet, but this is an important caveat.
breck 4y ago
Good list. I would add: 5. todos
pmoleri 4y ago
2. Is very applicable to workarounds often linked to 3rd party issues.
gremlinsinc 4y ago
These are almost exactly my own reasons, except I have #5 - annotations as needed for some php frameworks, and especially for ide intellisense. E.g. if the ide can't grok what a $var is you can do : /** @var Some\Namespace\To\Class $var */ $var = ... then when it reindexes things it has no problem tying everything together.
baby 4y ago
5. To add sections to code Code is writing, would you write a technical book without sections and chapters?
- feoren 4y ago
  If you can't organize your code into sections and chapters using the constructs provided by your programming language, for everyone's sake, get a better programming language. If you're not allowed to, get a better job. If you can't right now, then go ahead and use comments for that purpose, but I pity you.
  - baby 4y ago
    comments are constructs provided by the language. QED :)
    - feoren 4y ago
      It's a semantic argument, but I'd say they're clearly not language constructs. The format of a comment is completely unspecified by almost any language. In the cases of something like JavaDocs, it may be structured, but it's a very different language than the primary. The only mechanism provided by the language is the 1- or 2- character escape hatch for exiting that language and entering unstructured comment-land. I suppose emergency exits are "provided" by a movie theater, but I wouldn't call them a function of the theater, nor a normal part of the theater's usage (hopefully!).
      - baby 4y ago
        They’re specified by the english language
- HenriTEL 4y ago
  You should really use different modules/classes/files and folders/packages/namespaces for this.

spoiler 4y ago

I've not been doing 4, but it's s great idea. If someone's asked the question, it's likely it will come up again for the next person reading the code!

capableweb 4y ago
As an aside, my first try is always to try to clarify the code itself if someone has a specific question, so the obvious answer is in the code. But if I'm unable to signal that in code, a comment will do just fine.
- hakunin 4y ago
  I couldn't fit this part in my tweet, but this is an important caveat.

breck 4y ago

Good list. I would add: 5. todos

pmoleri 4y ago

2. Is very applicable to workarounds often linked to 3rd party issues.

gremlinsinc 4y ago

These are almost exactly my own reasons, except I have #5 - annotations as needed for some php frameworks, and especially for ide intellisense. E.g. if the ide can't grok what a $var is you can do : /** @var Some\Namespace\To\Class $var */ $var = ... then when it reindexes things it has no problem tying everything together.

baby 4y ago

5. To add sections to code Code is writing, would you write a technical book without sections and chapters?

feoren 4y ago
If you can't organize your code into sections and chapters using the constructs provided by your programming language, for everyone's sake, get a better programming language. If you're not allowed to, get a better job. If you can't right now, then go ahead and use comments for that purpose, but I pity you.
- baby 4y ago
  comments are constructs provided by the language. QED :)
  - feoren 4y ago
    It's a semantic argument, but I'd say they're clearly not language constructs. The format of a comment is completely unspecified by almost any language. In the cases of something like JavaDocs, it may be structured, but it's a very different language than the primary. The only mechanism provided by the language is the 1- or 2- character escape hatch for exiting that language and entering unstructured comment-land. I suppose emergency exits are "provided" by a movie theater, but I wouldn't call them a function of the theater, nor a normal part of the theater's usage (hopefully!).
    - baby 4y ago
      They’re specified by the english language
HenriTEL 4y ago
You should really use different modules/classes/files and folders/packages/namespaces for this.