Page MenuHomePhabricator

[docs] Add guidance on duplicating doc comments to CodingStandards
Needs RevisionPublic

Authored by asb on Feb 2 2018, 9:50 AM.

Details

Summary

Duplicating documentation comments for overridden methods adds a maintenance burden, and should be avoided. Discussed on llvm-dev: http://lists.llvm.org/pipermail/llvm-dev/2018-January/120882.html

Diff Detail

Event Timeline

asb created this revision.Feb 2 2018, 9:50 AM
reames requested changes to this revision.Feb 2 2018, 2:12 PM
reames added inline comments.
docs/CodingStandards.rst
324

I'd suggest reframing this to focus on what should you document for the override version. i.e. When documenting override methods, highlight the differences with parent implementation. Instead of duplicating the existing documentation, refer to it if needed. If the documentation for the overridden method is sufficient to document the override's behaviour, omit documentation of the override.

This revision now requires changes to proceed.Feb 2 2018, 2:12 PM
echristo added inline comments.
docs/CodingStandards.rst
324

+1

lattner added a subscriber: lattner.Feb 5 2018, 9:25 PM

Personally, I don't see the harm in duplicating the comments, and they are useful when you're not using doxygen or some other tool. You're talking about the overriden method situation, but another common one is when you define a class in an anonymous namespace and then implement it later in the same file. The implementation should certainly have a doc comment on it, and if it helps to understand the overview of what the struct is doing, then it makes sense to document it in the class definition as well.

Yes, of course the comments can get out of date, but so can code. I haven't heard of this being a code maintenance problem in practice.

-Chris

Here's a different way to interpret the current situation: instead of seeing the current behavior as "inconsistent", you could see it as "duplication only making sense in some cases". Realistically though, I agree that the code base is probably inconsistent as it is written by lots of people with different practices.

If you're interested in making this situation better, it would probably be effective to teach clang-tidy to complain about duplicated comment blocks that are larger than a certain threshold but slightly different.

-Chris