You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ignite.apache.org by Sergey Evdokimov <se...@gridgain.com> on 2015/07/30 15:39:46 UTC
Pointless javadocs in test code and private classes
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?
Re: Pointless javadocs in test code and private classes
Posted by Sergey Evdokimov <se...@gridgain.com>.
You have not to write those comments, we have a IDEA plugin that generates
those comments automatically. But it's a trash.
On Thu, Jul 30, 2015 at 6:12 PM, Alexey Kuznetsov <ak...@gridgain.com>
wrote:
> I do not agree. It is not so hard to write a couple of lines.
>
>
> On Thu, Jul 30, 2015 at 10:06 PM, Pavel Tupitsyn <pt...@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
> >
>
>
>
> --
> Alexey Kuznetsov
> GridGain Systems
> www.gridgain.com
>
Re: Pointless javadocs in test code and private classes
Posted by Alexey Kuznetsov <ak...@gridgain.com>.
I do not agree. It is not so hard to write a couple of lines.
On Thu, Jul 30, 2015 at 10:06 PM, Pavel Tupitsyn <pt...@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
>
--
Alexey Kuznetsov
GridGain Systems
www.gridgain.com
Re: Pointless javadocs in test code and private classes
Posted by Ivan Veselovskiy <iv...@gridgain.com>.
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 <ds...@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 <vo...@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 <se...@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
> > > > >
> > > >
> > >
> >
>
Re: Pointless javadocs in test code and private classes
Posted by Dmitriy Setrakyan <ds...@apache.org>.
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 <vo...@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 <se...@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
> > > >
> > >
> >
>
Re: Pointless javadocs in test code and private classes
Posted by Vladimir Ozerov <vo...@gridgain.com>.
+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 <se...@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 <se...@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
> > >
> >
>
Re: Pointless javadocs in test code and private classes
Posted by Sergi Vladykin <se...@gmail.com>.
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 <se...@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
> >
>
Re: Pointless javadocs in test code and private classes
Posted by Sergey Evdokimov <se...@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 <ak...@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 <pt...@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
>
Re: Pointless javadocs in test code and private classes
Posted by Alexey Kuznetsov <ak...@gridgain.com>.
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 <pt...@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 <pt...@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
Re: Pointless javadocs in test code and private classes
Posted by Pavel Tupitsyn <pt...@gridgain.com>.
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 <pt...@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
Re: Pointless javadocs in test code and private classes
Posted by Ivan Veselovskiy <iv...@gridgain.com>.
+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 <pt...@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
>
Re: Pointless javadocs in test code and private classes
Posted by Pavel Tupitsyn <pt...@gridgain.com>.
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 <se...@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