IMHO, requiring comments on trivial methods like setters and getters is often a net negative, but setting some standard could be useful.
On Mon, Jan 7, 2019 at 7:35 AM Jean-Baptiste Onofré <j...@nanthrax.net> wrote: > > Hi, > > for the presence of a comment on public method, it's a good idea. Now, > about the number of lines, not sure it's a good idea. I'm thinking about > the getter/setter which are public. Most of the time, the comment is > pretty simple (and useless ;)). > > Regards > JB > > On 07/01/2019 04:35, Ruoyun Huang wrote: > > Hi, everyone, > > > > > > We were wondering whether it is a good idea to make checkstyle > > enforce public method comments. Our current behavior of JavaDoc check is: > > > > 1. > > > > Missing Class javadoc comment is reported as error. > > > > 2. > > > > Method comment missing is explicitly allowed. see [1]. It is not > > even shown as warning. > > > > 3. > > > > The actual javadoc target gives warning when certain tags are > > missing in javadoc, but not if the whole comment is missing. > > > > > > How about we enforce method comments for **1) public method and 2) > > method that is longer than N lines**. (N=~30 seems a good number, > > leading to ~50 violations in current repository). I can find out the > > corresponding contributors to fill in the missing comments, before we > > turning the check fully on. > > > > > > One caveat though is that we might want skip this check on test code, > > but I am not sure yet if our current setup can easily handle separated > > rules for main code versus test code. > > > > > > Is this a good idea? Thoughts and suggestions? > > > > > > [1] > > https://github.com/apache/beam/blame/5ceffb246c0c38ad68dd208e951a1f39c90ef85c/sdks/java/build-tools/src/main/resources/beam/checkstyle.xml#L111 > > > > > > Cheers, > > > > -- > Jean-Baptiste Onofré > jbono...@apache.org > http://blog.nanthrax.net > Talend - http://www.talend.com
