[llvm-dev] Coding standards: duplicating method comments?

[Philip Reames via llvm-dev]

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