Header on Java source code files

[Lars Bruun-Hansen <lb...@gmail.com>]

I've noticed that AL2 license headers for Apache NetBeans in Java source
code files start with the Javadoc introducer, i.e. "/**" rather than just
"/*". Even on .c and .h files this is the case.

I've checked how the IDE itself does it on a fresh project where you ask it
to apply some type of license header: It will - correctly - start with
"/*", not "/**". I've also looked around how other projects do it, for
example the JDK itself : all examples I've found use "/*". It was also only
a "/*" back in Hg days.

By starting the license header with "/**" we are telling the Javadoc parser
that this is something it should pay attention to. Luckily on a standard
class source file, Javadoc will ignore such comment because it comes before
the package declaration. On a package-info file it won't be ignored, unless
another Javadoc entry follows it.

It may be minor, but I think it should be fixed. Better now than later.

Opinions on this?

Re: Header on Java source code files

[Victor Williams Stafusa da Silva <vi...@gmail.com>]

"/**" comments that are not intended to be parsed by the javadoc tool
should be considered as either an anti-pattern or a bug in my opinion.
There is simply no sane reason in doing that. "/**" comments should be used
only for javadocs and nothing more. For things that have nothing to do with
javadocs, the "//" and the standard "/*" comments should be used.

A related, but different, issue is that javadoc syntax in non-javadoc
comments is a problem too. Already saw many people using that in the form
of "/* (non-javadoc) @see blahblah */" comments, but can occasionally be
seen in other forms. This is an anti-pattern in my opinion.

2017-11-18 17:33 GMT-02:00 Lars Bruun-Hansen <lb...@gmail.com>:

> I've noticed that AL2 license headers for Apache NetBeans in Java source
> code files start with the Javadoc introducer, i.e. "/**" rather than just
> "/*". Even on .c and .h files this is the case.
>
> I've checked how the IDE itself does it on a fresh project where you ask it
> to apply some type of license header: It will - correctly - start with
> "/*", not "/**". I've also looked around how other projects do it, for
> example the JDK itself : all examples I've found use "/*". It was also only
> a "/*" back in Hg days.
>
> By starting the license header with "/**" we are telling the Javadoc parser
> that this is something it should pay attention to. Luckily on a standard
> class source file, Javadoc will ignore such comment because it comes before
> the package declaration. On a package-info file it won't be ignored, unless
> another Javadoc entry follows it.
>
> It may be minor, but I think it should be fixed. Better now than later.
>
> Opinions on this?
>