Hi, just a few thoughts:
For the tags: (we have no custom doclet for the tags, we need one at last) @blocking : I would consider this useful but you will only expect it in some IO stuff @nonblocking: pretty useless as this should be just the default assumption when calling a method @swt: Useless, see SWT Widgets, just throw an exception and mention this in the Javadoc @caching: Just describe that an operation is expensive, let the caller handle the caching. Anyways a good explanation cannot be autogenerated with a doclet for this tag IMO. Spending a few minutes to write some good Javadoc should just be fine. @swing ... ehh yes ? @nonReentrant this can only happen when exploiting the async behavior of SWT runnables, the code should handle this, there is no need for the developer that uses the API to take care of this @threadsafe ... this is what we expect from our code, otherwise just mention it in the javadoc @ui ... not very helpful, it is the same as @swt @valueObject ... not very helpful ... it is better to mention that a class (instance of it) is immutable For the rest: The listener conventions. I do not think that adding an event package gains someone any benefits. As for the naming. IMO it does not really matter if a listener is called IXYZ or just XYZ as long as every listener is named according to the convention. As for the adapter stuff, I personally prefer NullXZYListener instead of XYZAdapter but this is personal choice. The important thing that our convention has to be honored throughout the project. Any other thoughts ? BR, Stefan On 14.08.2015 13:24, Denis Washington wrote: > Hi, > > Over time I have noticed several instances where things recommended in > our Coding Conventions [1] are almost nowhere followed, or not followed > at all (anymore). The ones I found are: > > * The conventions say that listeners should always reside in an "events" > subpackage of the package they logically belong to. However, this is > never done anywhere in the core, and also not in the IntelliJ plugin. > As Stefan noted [2], the only place still using that convention is the > UI part of the Eclipse plugin. > > * Empty abstract classes for listeners should be called FooAdapter according > to the conventions (like in the Java standard library), but seem to be > consistently called AbstractFooListener instead. > > * The conventions recommend several Javadoc tags such as @ui (must be > called from the UI thread), @threadsafe, and others. However, with the > exception of @nonblocking and @blocking, none are really used (several > not at all): > > Tag # Uses > -------------------- > @blocking 28 > @nonblocking 16 > @swt 4 > @caching 2 > @swing 0 > @nonReentrant 0 > @threadsafe 0 > @ui 0 > @valueObject 0 > > > What to do about this? The pragmatic solution would be to just adapt the > conventions > to match the current practice in the code, rather than the other way around - > that > is, dropping mentions of unused tags, removing or altering rules that are > nowhere > followed, etc. What do you think? > > Regards, > Denis > > [1] http://www.saros-project.org/coderules > [2] > http://saros-build.imp.fu-berlin.de/gerrit/#/c/2807/3/de.fu_berlin.inf.dpp.core/src/de/fu_berlin/inf/dpp/editor/events/AbstractSharedEditorListener.java@1 > > ------------------------------------------------------------------------------ > _______________________________________________ > DPP-Devel mailing list > DPP-Devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/dpp-devel ------------------------------------------------------------------------------ _______________________________________________ DPP-Devel mailing list DPP-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/dpp-devel
