Le mardi 31 décembre 2013 à 10:29 -0500, John Myles White a écrit : > (31) “Avoid overcommenting” seems like a better phrase. What I’d like > to get across is that often comments are really formal specifications > and belong in a separate document. I use to fill the DataFrames > codebase with architectural design information as comments, which > started to become clutter that made the file hard to read over time.
If you keep this point about avoiding overcommenting, please also add one point about avoiding undercommenting. I agree that long architectural explanations or description of math formulas are better kept separate, but on the other hand code without any comment should not be encouraged. In particular, the purpose of each function should be documented using the meta-data system, the meaning of arguments should be made clear where it isn't completely self-evident, and inside the code every pattern which is not completely transparent would gain from being accompanied with a short word. Finally, I think one lesson of the documentation of large code bases (I'm thinking e.g. of GTK here) is that documentation that is kept separate from the code will inevitably get outdated. In R, the separation of the documentation of functions, their arguments and return values from their code is a pain, which lead to the introduction of things like Roxygen to work around this. So I think that only documentation which is relatively detached from the actual code, like (as you said) general architecture, specifications, math formulas and algorithms, should be separate. Things really tightly coupled with the code should be kept with it. That said, I really like the style guide! Regards
