Philip Reames via llvm-dev
2018-Feb-01 03:44 UTC
[llvm-dev] Coding standards: duplicating method comments?
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
Alex Bradbury via llvm-dev
2018-Feb-02 17:54 UTC
[llvm-dev] Coding standards: duplicating method comments?
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. > > +1Thanks 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