On 24.08.2015 11:23, Denis Washington wrote: > 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? It is quite normal that discussions normally ends like this. Do not ask me why but I think this is either due lack of knowledge regarding the topic, lack of time, or just lack of interest.
The other issue you currently mention (edits to the documentation / webpage) was one of the major concerns. Me and Holger pointed out that it would a good idea just to maintain the developer documentation (see http://saros-build.imp.fu-berlin.de/sarosGettingStarted/saros-getting-started.pdf) which could be updated through normal Gerrit Reviews and then add a process that transform the original XML document into Drupal pages. Unfortunately it seems that such a task was to hard for the assigned student. > 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
