Hello Tom! My comments inline...
> -----Original Message----- > From: Tom Morris [mailto:[EMAIL PROTECTED] > Sent: den 25 maj 2006 21:15 > To: [email protected] > Subject: RE: [argouml-dev] Coding conventions > > Linus said: > > > I have been stubborn about sticking to the Code > > Conventions for the Java Programming Language from Sun. > > but then goes on to describe several "interpretations," additions, and > personal preferences. True to my word though, I'm willing to acquiesce on > any of the mechanical stuff if there is tool support for it. I don't see > any > recent updates to eclipse-argo-codetemplates, eclipse-argo-formatter, or > eclipse-argo-prefs. Do you have private versions that you are using? Can > we get CVS updated appropriately? We have checkstyle in place with a configuration to support the styles that we are using. It has been more or less untouched since February 2004. Speaking of tool support in Eclipse, what we haven't discussed recently is how much we should enforce running checkstyle from within Eclipse. I have files in the Team Synchronization view that I never commit because the default setup doesn't have checklipse enabled in all the projects. If you are looking for tool support, this is perhaps the first step. I see no possibility to enable this in CVS. We don't have any possibilities to enter scripts in the CVS server. > > For statements also has the peculiarity that the > > initialization and the condition looks like statements. They > > end with ';' and everything. So I prefer writing them each on > > their own line if wrapping is needed. > > Preferences are fine for writing new code, but existing code shouldn't be > modified unless it clearly violates the coding conventions in a way that > makes it *necessary* to change it. > > > > 4. when reformatting old code, make the minimal change which will > bring > the code into conformance > > Do you agree that point #4 is a good idea? I think it's important to help > minimize code churn. Well, yes and no. I have done this on a file level. Let me explain what I have done. We have the checkstyle configuration (in /argouml/tools/checkstyle/checkstyle_argouml.xml) that is in tune with the Java Coding Standards that we have decided to use. We also have another checkstyle configuration file with a lot of good-to-have tests to further improve the quality of the code. It is the /argouml/tools/checkstyle/checkstyle_argouml_paranoid.xml file. Whenever a file contains a problem according to the first checkstyle configuration and I fix it, I also fix the things that are found with the second checkstyle configuration and things that my Eclipse configuration finds (like parameter hides field, and unused fields...). > > > #1: subkeys = new String[] {""}; > > > #2: subkeys = > > > new String[] { > > > "", > > > }; > > This is not stated in the Code Conventions. This comes from a > > combination of checkstyle rules (NoWhitespaceAfter (comman, > > left brace) and ArrayTrailingComma) together with the > > "higher-level breaks preferred" as above. > > Checkstyle is a tool to help use conform to the Sun conventions, so if > there's a mismatch, that's easy to fix. Even so, I see no Checkstyle > errors > or warnings about construct #1 when I run it. What checkstyle file are > you > using? Something different from checstyle_argouml in CVS? Also, > NoWhitespaceAfter won't be triggered by #1 because there is no whitespace > after the brace. Yeah, well, I don't know. I guess that I also have a ArrayTrailingComma check built into my head that wants to add the comma and also wanting every element in the array on a single line by its own. > > Either the private fields and methods are > > interesting to the person examining the class or they are > > not. If they are interesting, then the javadoc view could > > just as well contain their documentation. If they are not > > interesting, then why should the javadoc contain them at all? > > That's precisely the point. The Javadoc *shouldn't* contain > implementation > details at all. We use multiple levels of abstraction, but at any level > of > abstraction the internal implementation details aren't relevant to the > consumer of the implementation. Javadoc is about the API/interface, not > the > implementation. A private method *by definition* can't be used outside > the > class. It doesn't belong in the Javadoc. OK. I have removed the private and default fields and methods from the javadoc. In a couple of hours you will see the result in the nightly built javadoc. I still don't think this affects the author of the code. He should stick to writing javadoc comments on each class, method, and field anyway. > > If the <p> is put first on a line, the end of that section is > > not as clearly marked. Especially (in some cases that I have > > fixed) where the line with <p> is instead of the empty line. > > When you say "fixed" are you saying that this is covered by the Sun > conventions? Is there an Eclipse setting which supports the style you > want > to enforce? The disadvantage to enforcing a style not supported by the > tools is that it discourages developers from updating the comments (this > is > the reason leading asterisks were discouraged on block comments by most > coding conventions until the tools evolved to easily support rewrapping > them). No. No. This is currently only enforced by the paranoid file. > If I update a comment and rewrap it using Eclipse, are you going to "fix" > it > again? That type of dueling change is exactly the type of code churn that > coding standards are designed to avoid. If it is hard to distinguish the sections from each-other, I might fix it. /Linus --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
