> I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. To a point. Believe me, there are levels of repetition y

> I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. To a point. Believe me, there are levels of repetition you would find less tolerable than a lack of documentation. Here's a real world example: we had a bunch of classes with lots of attributes. The getters and setters for those attributes were automatically generated (with a macro), because we had lots and lots of them. In the headers however, we wrote the prototypes in full, so the tools could find them more easily: Foo getFoo(); Bar getBar(); Baz getBaz(); void setFoo(const Foo &foo); void setBar(const Bar &bar); void setBaz(const Baz &baz); So far so good. Now documentation is an important thing. So important in fact that we had to document every single method in all classes. And since we were using Doxygen, we were a bit constrained. Foo getFoo(); ///< Get foo Bar getBar(); ///< Get bar Baz getBaz(); ///< Get baz void setFoo(const Foo &foo); ///< Set foo void setBar(const Bar &bar); ///< Set bar void setBaz(const Baz &baz); ///< Set baz OK that's redundant, not too bad, and QA is happy now. Well, no. First, we are supposed to be using Javadoc style documentation. Second, we need to document every arguments, and the return values. How are we supposed to understand a getter if we don't document its return value? /** * Get foo * * @return foo */ Foo getFoo(); /** * Get bar * * @return bar */ Bar getBar(); /** * Get baz * * @return baz */ Baz getBaz(); /** * Set foo * * @foo The new Foo */ void setFoo(const Foo &foo); /** * Set bar * * @bar The new Bar */ void setBar(const Bar &bar); /** * Set baz * * @baz The new Baz */ void setBaz(const Baz &baz); And so on, often for 20 attributes instead of just 3. I am not even kidding. Now we could say it's just a matter of space, but it isn't: sometimes, there was an attribute that was a bit special, and the comment reflected that: /** * Set wiz * * @baz The new Wiz. Must not be Merlin. */ void setWiz(const Wiz &wiz); Except the additional comment could as well be absent, because it was totally lost in the noise. I've missed several cogent pieces of information that way. Worse, the tech lead, who acknowledged that this practice was useless at best, and had the clout to have this restriction relaxed, refused to do so. To this day I'm not sure why. I have a couple hypotheses (plain inertia, don't fix what's not blatantly broken, don't want to argue with QA, afraid of regulation…), but nothing solid. If I had to chose between no comment at all and that, I'm not sure I would chose that. Sure, I would lose valuable comments, but if I already lost them because of sheer noise, I didn't lose much at all.