I like Milan's phrasing and I agree with it. I think we can use that phrasing in the style guide. I propose something like this:
---- === Source comments Avoid overcommenting: Architectural explanations and descriptions of math formulas are important, but should be kept in a separate file. Avoid undercommenting: Explain the purpose of each function, the meaning of each argument (unless they are truly self-evident), and every pattern that is not truly transparent. The goal is to strike a balance between keeping the documentation updated, and minimizing the clutter inside source files. In general, explanations tightly coupled to the code should be in the code and explanations that are detached from the code should be outside the code. ---- On 1 January 2014 09:01, Milan Bouchet-Valat <[email protected]> wrote: > 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 -- When an engineer says that something can't be done, it's a code phrase that means it's not fun to do.
