[wwwigham]

The article mentions the importance of comments and documentation inline in code. I tend to agree - well-written code is great and all, but a good comment can bring in context external to the code and make _why_ code is what it is more clear to future readers. And reviewers. Comments explaining _what_ code does largely aren't needed - that's evident from usage. But the _why_? Some people would say code which can't be explained by one liner comments is "too clever". Well, I'm inclined to disagree - it's hard to fit a full historical justification for an awkward handling of an edge case into a single line. I once wrote a 17 line long comment above an 8 line diff; that much context felt justified to explain the odd code. A reviewer, hilariously, had this to say:

    This right here is "here be dragons" commenting level Double Dragon.

When I come back to code I've written long in the future, I think I'll be happier to have written the detailed "commenting level Double Dragon" long comments, over the more ambiguous yet still traditional `// HERE BE DRAGONS`. Mostly because that comment will give me the context I need to know if any of that _why_ has changed and thus in what way it's likely safe to change the commented code.

[gigatexal]

Please, please comment code. Junior devs like myself will thank you senior devs for throwing us a bone.

[zimpenfish]

As do us old senior contracting devs who have to come in at short notice and pick up a strange codebase.

[tetha]

To me, there is also the question of change frequency. Of course, it's a guesstimate all the time, but things that look to be rarely-changing (and usually ends up being high-impact) deserve over-documentation. Something like our AWS VPC, DNS and DHCP setups and their expected change modes and their effects are very well documented. It rarely changes and if it breaks, everything breaks. The fundamentals of our disk setups and disk encryption in ansible is carefully documented because if that breaks, things will go hairy.

In those cases, having a lot of documentation, speeds up changes because you can store months and years of deliberation and decisions in these comments.