[ http://issues.apache.org/jira/browse/JCR-97?page=comments#action_12456799 ] Jan Kuzniak commented on JCR-97: --------------------------------
> i also consider changes like the following as rather awkward Javadoc formatting across whole Jackrabbit is really inconsistent. I have chosen the most readable format amongst those that I have found here and I use it consistently. Also this is Sun formatting convention that I thought Jackrabbit checkstyle is based on. Please correct me if I am wrong. And one word about this format advantages: Please consider common case like "@param number number of occurences in text". When written in one line seems strange, but when broken after param name and intended seems clear (at least to me). re second example - corrected in next patch (coming soon). And about blind conformance - ok, you're right. I will watch out more and try to find better compromises. I promise :-) > Improve Checkstyle conformance > ------------------------------ > > Key: JCR-97 > URL: http://issues.apache.org/jira/browse/JCR-97 > Project: Jackrabbit > Issue Type: Improvement > Reporter: Jukka Zitting > Priority: Minor > Attachments: jackrabbitAPICheckstylePatch.patch, > jackrabbitCoreClusterCleanup.patch, jackrabbitCoreConfigCleanup.patch, > jackrabbitCoreFsDbCleanup.patch, jackrabbitCoreUnnecessaryCodeCleanup.patch > > > This is an ongoing meta-issue for improving the Checkstyle conformance of the > Jackrabbit codebase. > Checkstyle (http://checkstyle.sourceforge.net/) is an automated tool for > checking conformance with coding standard and good coding style. A Checkstyle > report for Jackrabbit can be generated by running "maven checkstyle". > Currently the Jackrabbit Checkstyle report contains thousands of trivial > problems like unused imports and minor formatting issues. While it would be > possible to just remove those checks from the Jackrabbit Checkstyle > configuration, it would certainly be better to fix the real issues. After > fixing the trivial problems, the Checkstyle reports become much more valuable > tools in locating troublesome code and identifying chances for improvement. > While this issue remains open, you have an open mandate to improve the > standards conformance and coding style of the Jackrabbit sources. This > mandate applies only to changes that fix problems reported by Checkstyle > while making no changes to the external interface or behaviour of the changed > code. > The commit messages of such Checkstyle improvements should be labeled with > the Jira key of this issue (JCR-97) to mark the changes as style-only. This > way other committers will have easier time reviewing your changes for bugs or > other unexpected side-effects. > If you are not a Jackrabbit committer, but want to help improve the > Checkstyle conformance, you can make your changes using sources from > anonymous subversion and send your changes as an attachment to this issue. > Please see the Javadoc improvement issue JCR-73 for details. > PS. Blind conformance to style guides is seldom beneficial. Please remember > that the goal of this issue is to improve Jackrabbit code, not just the > Checkstyle output! -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
