Maxim,
> I'd prefer to leave the current situation with Javadoc as it is and just to
> ask to apply the patch [1][2]. Can you? :-)
You caught me. I left my comments for that PR
.Pavel and all,
> I think that API of our core internal things like PageMemory, WAL, all
> existing managers and processors should be as well documented as possible.
No doubts here.
> Documentation should be a result of a proper code review.
I suppose it does not mean that documentation should be written after
a review. I suppose it means that we should not have a poor
documentation *after* a review. Overall, Pavel's last message conforms
well with my opinion on the subject.
чт, 8 авг. 2019 г. в 18:34, Pavel Kovalenko :
>
> I can agree that some part of javadocs we have is useless. It relates to
> DTOs, getters/setters without side-effects, short self-descriptive methods.
> In an ideal world, proper modularization of architecture, leading to
> KISS/SOLID/DRY/etc. principles, writing self-documented code should result
> in javadocs disappearing, as they become not needed.
> We live in a not ideal world. We don't have good architecture and can't
> always lead to mentioned principles, because we need sometimes sacrifice
> readability for optimization, fixing a critical bug, etc.
> I think that API of our core internal things like PageMemory, WAL, all
> existing managers and processors should be as well documented as possible.
> If a developer uses some module / manager / processor without looking
> inside, reading the only description of public methods, it's a good sign
> that this part of the functionality is well documented.
> Internal implementation should be also clear for a developer who likes to
> make a change inside it. Every optimization, avoiding race-condition, not
> obvious thing and especially crutch must be documented as detailed as
> possible.
> Documentation should be a result of a proper code review. If a reviewer has
> questions regarding any code line it should be either refactored to make
> this thing obvious or well documented.
> If a class or method is self-documented and obvious there is no need to
> document it anyway.
> if each person takes the code review as seriously as possible,
> documentation and code will be better automatically.
> Mandatory documentation in places where it's really not needed looks like a
> burden. A developer will avoid write it properly everywhere or do it "just
> for check" and this will influence on documentation with the negative side.
> Flexible approach with mandatory / optional javadocs with good code review
> will result in readability improvement overall.
>
>
> чт, 8 авг. 2019 г. в 17:52, Maxim Muzafarov :
>
> > Ivan,
> >
> > It is not a problem to check Javadocs at the moment code syle checking
> > performed, but do we really need this? And the human-factor you
> > mentioned above is also related to the `self-descriptive` names. I
> > assume, that someone now is desiring to use single-letter variables
> > and single-letter class names to save space an time. We will always
> > have such an opinion race.
> >
> > I'd prefer to leave the current situation with Javadoc as it is and
> > just to ask to apply the patch [1][2]. Can you? :-)
> >
> > [1] https://issues.apache.org/jira/browse/IGNITE-12051
> > [2] https://github.com/apache/ignite/pull/6760
> >
> > On Thu, 8 Aug 2019 at 17:24, Павлухин Иван wrote:
> > >
> > > Maxim,
> > >
> > > My main concern here is a human factor. Humans are usually not so good
> > > in keeping documentation always in sync with a code. Examples from an
> > > actual PR:
> > > /**
> > > * @param nodeId The remote node id.
> > > * @param channel The channel to notify listeners with.
> > > */
> > > private void onChannelOpened0(UUID nodeId, GridIoMessage initMsg,
> > > Channel channel)
> > >
> > > First, there is a mismatch between number of parameters in javadoc and
> > > code. Second, e.g. nodeId name can be made self-descriptive rmtNodeId
> > > name.
> > >
> > > Mandatory javadocs do not imply good javadocs. Good javadocs do not
> > > imply javadocs for every method and field. For me, mandatory and good
> > > javadocs are like communism. Sounds quite nice in theory, but not
> > > feasible in practice.
> > >
> > > чт, 8 авг. 2019 г. в 16:55, Denis Garus :
> > > >
> > > > Thank you, Maxim.
> > > >
> > > > >>On what we are trying to save by making Javadoc optional?
> > > >
> > > > Space and time.
> > > >
> > > > I doubt that we need a verbal description of what private method make.
> > > > Why we need it if we just can read the code?
> > > >
> > > > Bright examples:
> > > >
> > > > /**
> > > > * @param helper Helper to attach to kernal context.
> > > > */
> > > > private void addHelper(Object helper) {
> > > > ctx.addHelper(helper);
> > > > }
> > > >
> > > > /**
> > > > * Gets "on" or "off" string for given boolean value.
> > > > *
> > > > * @param b Boolean value to convert.
> > > > * @return Result string.
> > > > */
> > > > private String
