ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ivan Veselovskiy <iveselovs...@gridgain.com>
Subject Re: Pointless javadocs in test code and private classes
Date Fri, 31 Jul 2015 10:29:26 GMT
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 <dsetrakyan@apache.org>
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 <vozerov@gridgain.com>
> 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 <
> sergi.vladykin@gmail.com
> > >
> > 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 <sevdokimov@gridgain.com>:
> > >
> > > > 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 <
> > > akuznetsov@gridgain.com
> > > > >
> > > > 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 <
> > > ptupitsyn@gridgain.com
> > > > >
> > > > > 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 <
> > > > > > iveselovskiy@gridgain.com
> > > > > > > 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 <
> > > > > ptupitsyn@gridgain.com>
> > > > > > > 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
<
> > > > > > > sevdokimov@gridgain.com
> > > > > > > > >
> > > > > > > > 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
> > > > >
> > > >
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message