llvm dev - Feb 2018 - Coding standards: duplicating method comments?

A quick coding standards question. The current coding standards doc
has helpful guidance on Doxygen comments and the like:
https://llvm.org/docs/CodingStandards.html#source-code-formatting

One aspect which isn't explicit is the policy on duplicating code
comments for subclasses. To modify an example from that doc:

"""
// In Something.h:

/// An abstraction for some complicated thing.
class Something {
public:
  /// Does foo and bar.
  virtual void fooBar();
};
"""

Suppose we define TargetSomething.h, and give the same comment for fooBar there:
"""
class TargetSomething : public Something {
public:
  /// Does foo and bar.
  void fooBar() override;
};
"""

Is this bad style? It seems the current codebase is inconsistent on
this point. The upside of such duplication is that it reduces the need
to cross-reference to other files when using a dumb editor. The
disadvantage is that duplicated comments add maintenance burden just
like duplicated code.

Thanks,

Alex

> On Jan 30, 2018, at 11:56 AM, Alex Bradbury via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> A quick coding standards question. The current coding standards doc
> has helpful guidance on Doxygen comments and the like:
> https://llvm.org/docs/CodingStandards.html#source-code-formatting
> 
> One aspect which isn't explicit is the policy on duplicating code
> comments for subclasses. To modify an example from that doc:
> 
> """
> // In Something.h:
> 
> /// An abstraction for some complicated thing.
> class Something {
> public:
>  /// Does foo and bar.
>  virtual void fooBar();
> };
> """
> 
> Suppose we define TargetSomething.h, and give the same comment for fooBar
there:
> """
> class TargetSomething : public Something {
> public:
>  /// Does foo and bar.
>  void fooBar() override;
> };
> """
> 
> Is this bad style? It seems the current codebase is inconsistent on
> this point. The upside of such duplication is that it reduces the need
> to cross-reference to other files when using a dumb editor. The
> disadvantage is that duplicated comments add maintenance burden just
> like duplicated code.
I usually just don't comment overrides.

If you really want to you could probably use
/// \copydoc Something::fooBar()

- Matthias

On 30 Jan 2018, at 19:56, Alex Bradbury via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> Is this bad style? It seems the current codebase is inconsistent on
> this point. The upside of such duplication is that it reduces the need
> to cross-reference to other files when using a dumb editor.
I generally use the rendered docs on the LLVM web site when using a dumb editor,
so haven’t found this to be a problem.
> The
> disadvantage is that duplicated comments add maintenance burden just
> like duplicated code.
Indeed.  It can lead to stale comments if the subclass is not updated when the
superclass is.  I also find these comments misleading: if an overridden method
has a comment, I expect it to tell me what is different between this and the
superclass’ definition (i.e. what I, as a caller of this method, should be aware
of if I call this version and not the superclass version).  If it is just the
superclass’s definition applied to the subclass, then a comment is confusing.

David

On 01/31/2018 02:37 AM, David Chisnall via llvm-dev
wrote:
> On 30 Jan 2018, at 19:56, Alex Bradbury via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
>> Is this bad style? It seems the current codebase is inconsistent on
>> this point. The upside of such duplication is that it reduces the need
>> to cross-reference to other files when using a dumb editor.
> I generally use the rendered docs on the LLVM web site when using a dumb
editor, so haven’t found this to be a problem.
>
>> The
>> disadvantage is that duplicated comments add maintenance burden just
>> like duplicated code.
> Indeed.  It can lead to stale comments if the subclass is not updated when
the superclass is.  I also find these comments misleading: if an overridden
method has a comment, I expect it to tell me what is different between this and
the superclass’ definition (i.e. what I, as a caller of this method, should be
aware of if I call this version and not the superclass version).  If it is just
the superclass’s definition applied to the subclass, then a comment is
confusing.
+1
>
> David
>
>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev