[hibernate-dev] OGM: CheckStyle and imports due to JavaDoc comments

[Gunnar Morling]

2013/7/31 Sanne Grinovero <sanne at hibernate.org>

> On 31 July 2013 09:41, Gunnar Morling <gunnar at hibernate.org> wrote:
> > 2013/7/31 Hardy Ferentschik <hardy at hibernate.org>
> >
> >> Hi,
> >>
> >> Personally I prefer to include a class via fully qualified name if it is
> >> only used in the javadocs.
> >> I think the readability does not suffer too much and adding an actual
> >> import has actually
> >> runtime consequences. We already had cases where a javadoc import
> caused a
> >> hard link
> >> between code which is otherwise decoupled.
> >>
> >
> > WDYM exactly by "hard link" in this context? Is it about referencing a
> type
> > from an optional dependency which might not be present at runtime?
> >
> > I just tried out this scenario (adding an import statement just for
> JavaDoc
> > to a type which is not present at runtime) and still could execute the
> > importing class without problems. Only when accessing the imported type
> in
> > the actual code I'm getting a CNFE. But this might be specific to the VM
> in
> > use, not sure.
>
> It is VM specific indeed, and sensitive to situation as to prevent
> circularity reference loading it never loads all imports aggressively,
> but some might depending on the moon phase :-)
> AFAIR IBM's JVM eagerly verifies class definition availability (but
> does not necessarily initialize the class), and it wouldn't surprise
> me even hotspot's behaviour could depend on specific situations and/or
> obscure flags.. I don't really know how to write a comprehensive test
> to showcase this but let's admit a simple test isn't enough to cover
> all situations.
>

Makes sense. There wouldn't be a problem in most cases (e.g. when
referencing a class from the same module), but it's better to keep the rule
as is to be on the safe side.


> I'd expect more recent compilers to remove such dead imports, but
> given it's not a big deal to remove these in the sources I'd rather be
> safe: we had problems with such imports in the past.
> I guess ideally we'd want IDEs to warn about it, I haven't seen an
> option for this (other than checkstyle integration plugins).
>

Indeed it's Eclipse which created these imports. There is a feature request
for making this configurable (
https://bugs.eclipse.org/bugs/show_bug.cgi?id=128661) but this is
unresolved.


> Sanne
>


>
> >
> > So if you guys are concerned about this case then let's better keep it as
> > is.
> >
> >
> >
> >>
> >> Even the check stye documentation recommends against it in the
> >> configuration
> >> of Unused Imports -
> >> http://checkstyle.sourceforge.net/config_imports.html#UnusedImports.
> >>
> >> --Hardy
> >>
> >>
> >> On 31 Jan 2013, at 9:33 AM, Gunnar Morling <gunnar at hibernate.org>
> wrote:
> >>
> >> > Hi,
> >> >
> >> > Currently CheckStyle raises an error due to an "unused import" if a
> class
> >> > imports types which are only referenced in JavaDoc comments. This
> issue
> >> > occurs for instance when referring to a super type in the comments
> while
> >> > only sub-types are used in the actual code:
> >> >
> >> >    /**
> >> >     * This factory creates {@link Service} objects.
> >> >     */
> >> >    public class ServiceFactory {
> >> >
> >> >        FooService getFooService() { ... }
> >> >    }
> >> >
> >> > Another example is "high-level" documentation on a central type of an
> API
> >> > (e.g. its entry point) which refers to types actually used by specific
> >> > parts of the API but not the entry point itself. In that case it can
> >> still
> >> > make sense to mention these types in the high-level docs.
> >> >
> >> > To work around the issue one could use the FQN in the JavaDoc or just
> >> > format it as {@code}, but both makes up for less readable
> documentation
> >> IMO.
> >> >
> >> > Personally I don't see a problem with this kind of import and thus
> >> suggest
> >> > to loosen that CS rule accordingly (it can be configured to take
> JavaDocs
> >> > into account). WDYT?
> >> >
> >> > --Gunnar
> >> > _______________________________________________
> >> > hibernate-dev mailing list
> >> > hibernate-dev at lists.jboss.org
> >> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >>
> >>
> > _______________________________________________
> > hibernate-dev mailing list
> > hibernate-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>