I personalty thought this was more or less finished (as the use of the code-conventions are indeed interesting ;-)
but instead of silently agreeing to your suggestion Denis - I vote to keep the @blocking and @nonblocking tags in our conventions and get rid of all others. I personally think, that it is not so clear when to use @nonblocking (just judging by it's tag name - as Stefan mentioned, "nonblocking" is what you would expect from a method, if not mentioned otherwise). The idea of including the documentation into our review is quite nice btw. Who want's to do it :-P - maybe a topic on the theses page? PS: I can edit this page Denis, so I don't know what is the reason why you can't - but it's certainly not "locked" for changes. Did you use https? 2015-08-24 11:23 GMT+02:00 Denis Washington <de...@denisw.de>: > 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: > > This discussion has died out now, but do we still agree that the rules > about the > "events" subpackage and the the *Adapter naming for abstract listener > classes > should be removed? If yes, we should just make these changes now. I > actually > wanted to make them, but didn't find a way to edit the page even after I > logged > in. Is the page somehow locked for editing? > > With regards to the tags, I propose that we either > > * remove all the tags from the docs (and code) > > * remove all tags except for @blocking and @nonblocking > > and perhaps add a section about things that should be mentioned in the > JavaDocs, > without formalizing them as JavaDoc tags (e.g. something like "If the > method potentially > blocks for a long time, mention this in the JavaDoc comment"). > > Regards, > Denis > > > * 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/dp > > p/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
