ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vladimir Ozerov <voze...@gridgain.com>
Subject Re: Pointless javadocs in test code and private classes
Date Thu, 30 Jul 2015 19:29:13 GMT
+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