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

[Alex Bradbury via llvm-dev]

On 1 February 2018 at 03:44, Philip Reames <listmail at philipreames.com> wrote:
>
>
> 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

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