This should be interesting…
“Paradoxically, we found that developers appreciate the value of header comments and estimate that they are worth the investment in time, but nevertheless they tend not to write such documentation in their own code. Reasons for not writing header comments vary from the belief that code should be self-documenting to concern that documentation will not be kept up-to-date.”
https://arxiv.org/abs/2401.07704
Mastodon Source 🐘
“Two said that documentation is forbidden”
Didn’t expect this.
Mastodon Source 🐘
“It is important to apply judgment, and only document functions that need it — either because they are part of an API or because they are complex. An easy test is to verify that you have what to say beyond the obvious from the function declaration. In these cases, it is important to apply documentation guidelines which correspond to what developers want and need, especially regarding the provision of examples of usage.”