ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sergey Evdokimov <sevdoki...@gridgain.com>
Subject Re: Pointless javadocs in test code and private classes
Date Thu, 30 Jul 2015 16:44:37 GMT
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