jackrabbit-oak-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mete Atamel <mata...@adobe.com>
Subject Re: Javadocs "@see also"
Date Thu, 10 May 2012 13:46:00 GMT
Good points. I also find comments like "logger instance" below quite
irritating. Comments are supposed to add further understanding that code.
Everyone looking at that log definition code knows that it's a logger
instance, so stressing that again in comments just adds noise, nothing
else...

I see this quite a lot in Jackrabbit codebase, so hopefully the next
version will avoid unnecessary comments.

Best,
Mete

On 5/10/12 3:38 PM, "Thomas Mueller" <mueller@adobe.com> wrote:

>Hi,
>
>A minor issue: some of us use "@see also" javadocs and some not. For
>example:
>
>    /**
>     * @see Object#hashCode()
>     */
>     @Override
>    public int hashCode() {
>        return value.hashCode();
>    }
>
>I find it kind of useless to write such javadoc tags, because javadoc
>anyway adds a link in the "Overrides:" section (a link to the exact same
>location). So if we write such javadoc tags, the only result is that the
>generated javadoc has two links instead of one.
>
>Therefore, I suggest we don't spend the time to manually write such tags.
>At least I will not. If you have the IDE configured to do that
>automatically then that's another issue, but I will not configure my IDE
>to do it.
>
>By the way, I also find generated javadocs of the following kind kind of
>useless:
>
>/**
> * ValueImpl...
> */
>public class ValueImpl implements Value {
>
>    /**
>     * logger instance
>     */
>    private static final Logger log =
>LoggerFactory.getLogger(ValueImpl.class);
>
>But in this case at least it reduces the number of warnings from the IDE.
>
>Regards,
>Thomas
>
>
>
>
>


Mime
View raw message