Re:Drunk Post: Things I've Learned as a Sr Engineer
by MaxBarraclough on Sunday May 30, 2021 @12:44PM
(#27334490)
> If you’re doing something that’s not immediately obvious, explain what you’re doing!
Agreed. Comments have their place, and some code is unavoidably involved, just by the nature of unavoidable complexity. The solution isn't always to write simple code. If it were, we wouldn't bother studying clever and efficient algorithms.
Also, it's important to ensure comments are updated when code is changed. I don't know who originally said it: Stale and inaccurate comments are no longer comments, they're lies.
That blog post looks worth reading properly, I admit so far I've only skimmed it.
Re:Drunk Post: Things I've Learned as a Sr Engineer
by craftinator on Sunday May 30, 2021 @03:19PM
(#27335827)
The mantra I use with my team is "comment the details, document the strategy".
Re:Drunk Post: Things I've Learned as a Sr Engineer
by MaxBarraclough on Sunday May 30, 2021 @04:30PM
(#27336449)
See the taxonomy of documentation solutions, https://documentation.divio.com/ and https://youtu.be/t4vKPhjcMZg?t=324
[0]: http://antirez.com/news/124