2013/7/31 Sanne Grinovero <sa...@hibernate.org> > On 31 July 2013 09:41, Gunnar Morling <gun...@hibernate.org> wrote: > > 2013/7/31 Hardy Ferentschik <ha...@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 <gun...@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@lists.jboss.org > >> > https://lists.jboss.org/mailman/listinfo/hibernate-dev > >> > >> > > _______________________________________________ > > hibernate-dev mailing list > > hibernate-dev@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
