[llvm] r189704 - Remove the suggestion to not duplicate comments in header and

Benjamin Kramer benny.kra at gmail.com
Fri Aug 30 16:24:53 PDT 2013


On 31.08.2013, at 01:06, Chris Lattner <sabre at nondot.org> wrote:

> Author: lattner
> Date: Fri Aug 30 18:06:20 2013
> New Revision: 189704
> 
> URL: http://llvm.org/viewvc/llvm-project?rev=189704&view=rev
> Log:
> Remove the suggestion to not duplicate comments in header and
> implementation files.  While doc generation systems don't need this,
> humans do benefit from it.  Not everyone reads all code through doxygen.

I disagree.

The big problem with duplicated comments is that now not just one comment gets out of date but we get two comments that diverge over time. I've seen this happening in LLVM several times. That alone is enough reason for not duplicating the comment.

While it's true that few people actually read code through doxygen there are many tools (*cough* clang *cough*) that can consume doxygen comments and I hope that the usual editors will grow plugins that display them through libclang.

- Ben 

> 
> Modified:
>    llvm/trunk/docs/CodingStandards.rst
> 
> Modified: llvm/trunk/docs/CodingStandards.rst
> URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.rst?rev=189704&r1=189703&r2=189704&view=diff
> ==============================================================================
> --- llvm/trunk/docs/CodingStandards.rst (original)
> +++ llvm/trunk/docs/CodingStandards.rst Fri Aug 30 18:06:20 2013
> @@ -195,13 +195,6 @@ A documentation comment that uses all Do
>   /// \returns true on success.
>   bool fooBar(bool Baz, StringRef Quux, std::vector<int> &Result);
> 
> -Don't duplicate the documentation comment in the header file and in the
> -implementation file.  Put the documentation comments for public APIs into the
> -header file.  Documentation comments for private APIs can go to the
> -implementation file.  In any case, implementation files can include additional
> -comments (not necessarily in Doxygen markup) to explain implementation details
> -as needed.
> -
> Don't duplicate function or class name at the beginning of the comment.
> For humans it is obvious which function or class is being documented;
> automatic documentation processing tools are smart enough to bind the comment
> 
> 
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits





More information about the llvm-commits mailing list