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

I usually just don't comment overrides.

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

- Matthias

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

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

Thanks everyone, I'm in full agreement but thought I'd check as there
are quite a few instances of copied comments in the current codebase.
Patch submitted for review https://reviews.llvm.org/D42850

Best,

Alex