Rough statistic of empty javadocs: incubator-ignite$ grep -rnE '/\*\*\s+\*/' . | grep -v '^Binary file' | wc -l *6858*
ggprivate$ grep -rnE '/\*\*\s+\*/' . | grep -v '^Binary file' | wc -l *3560* --ivan On Thu, Jul 30, 2015 at 10:42 PM, Dmitriy Setrakyan <[email protected]> wrote: > I am also +1 for keeping things as is. > > The code is consistent right now and everyone follows this rule. If we > change it, we will end up with code that has javadoc in some places and > does not in others. > > D. > > On Thu, Jul 30, 2015 at 12:29 PM, Vladimir Ozerov <[email protected]> > wrote: > > > +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 > > > > > > > > > > > > > > >
