+1 for keeping things as is. I honestly do not believe that writting JavaDocs consume statistically significant percentage of commiter/contributor time. Moreover different people tend to differently evaluate "complexity" of code. Mature igniter will have much more "obvious" things than a newcomer. It is better to have a strict rule instead of relying on personal feelings.
On Thu, Jul 30, 2015 at 10:06 PM, Sergi Vladykin <[email protected]> wrote: > I think it is a matter of taste, nothing more than that. Personally I > prefer to have method javadocs mostly to have parameters and return value > described even if method name is meaningful enough. I don't believe that > saving few lines of code will give you something, lets keep things as it is > now. > > Sergi > > 2015-07-30 19:44 GMT+03:00 Sergey Evdokimov <[email protected]>: > > > Alexey, > > > > By default IDEA does not show warning for methods without comments. > > GridGain IDEA plugin adds that warning. > > It's normal to keep method without comment if comment is not needed, IDEA > > cannot warn it in default configuration. Only Ignite has guideline > "Comment > > ALL members and classes". > > > > On Thu, Jul 30, 2015 at 7:20 PM, Alexey Kuznetsov < > [email protected] > > > > > wrote: > > > > > Pavel, > > > > > > I'm working in IDEA. > > > > > > And it is configured to show warnings if smth is wrong in code (one of > > this > > > is a missing javadocs). > > > > > > I like to have a "green check mark" instead of "yellow square warning" > > when > > > I opened file in IDEA. > > > > > > I feeling uncomfortable until I'm not cleaned every warning in my code. > > > > > > And I do not understand how comments could distract anybody? > > > > > > > > > On Thu, Jul 30, 2015 at 10:26 PM, Pavel Tupitsyn < > [email protected] > > > > > > wrote: > > > > > > > Alexey, "it is not so hard to do X" is not the reason to do X. You > > don't > > > > reinvent library functions when they are not so hard, do you? > > > > > > > > Any extra work that can be avoided should be avoided. > > > > We all know that concentration is very important during programming. > > > These > > > > useless empty comments distract you both when you write code and read > > it. > > > > > > > > On Thu, Jul 30, 2015 at 6:16 PM, Ivan Veselovskiy < > > > > [email protected] > > > > > wrote: > > > > > > > > > +1 > > > > > > > > > > As per my experience, the comments are useful not when they belong > to > > > > > members of specific visibility, but when they contain a sensible > > > > > information. > > > > > For example, even in public API public int getLength() with > comment > > > /** > > > > > Gets the length. */ is senseless , because it contains only obvious > > > > > information. > > > > > > > > > > --ivan > > > > > > > > > > On Thu, Jul 30, 2015 at 6:06 PM, Pavel Tupitsyn < > > > [email protected]> > > > > > wrote: > > > > > > > > > > > I agree. > > > > > > > > > > > > Public things (classes/interfaces/methods/etc) should always have > > > > > non-empty > > > > > > docs, I think, but private things rarely need it. > > > > > > > > > > > > On Thu, Jul 30, 2015 at 4:39 PM, Sergey Evdokimov < > > > > > [email protected] > > > > > > > > > > > > > wrote: > > > > > > > > > > > > > Hello, > > > > > > > > > > > > > > In the Ignite code each class / method / field has a javadoc. > > Test > > > > code > > > > > > and > > > > > > > code in the private packages must have javadocs too. In the > most > > > > cases > > > > > > > javadoc does not has value, it just duplicates member name. > This > > > > > > pointless > > > > > > > javadoc take developer's time and takes lines in the editor. > > > > > Furthermore > > > > > > > pointless javadoc distract attention from the real javadoc. > > > > > > > > > > > > > > May be we should change our guidelines. What do you think? > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > -- > > > > > > Pavel Tupitsyn > > > > > > GridGain Systems, Inc. > > > > > > www.gridgain.com > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > -- > > > > Pavel Tupitsyn > > > > GridGain Systems, Inc. > > > > www.gridgain.com > > > > > > > > > > > > > > > > -- > > > Alexey Kuznetsov > > > GridGain Systems > > > www.gridgain.com > > > > > >
