> I have no time to spell it out already, but just a few comments. > > > * Coding style > > I think you are creating overlap with > http://www.mmbase.org/docs/backenddevelopers/codingstandards.html > > This is not necessarily bad, if at least our goal is to end > up with one authorative coding standard, and not more. > > > Portability > > > > Portability is one of the principal advantages of using Java. > > Guidelines for ensuring that a Java application remains > portable are: > > * do not use hard coded file names and paths - use the > File class, and > > allow file paths to be configured during deployment. > > * remember that some systems have case sensitive file > names (Unix), > > while > > others do not (Windows) > > I would go even futher and say: > > Don't use the File class at all, but suppose that everything > is a 'resource', so use the ResourceLoader, > ServletContext.getResource or Class.getResource. This will > make sure that your app and mmbase would also work in a war. > The windows vs unix issue doesn't play then either. > > > > @@TODO@@ Add more code standards > > I would once again point out the existing code standards, and > would really like that your ideas are incorporated in it.
The coding standards on the mmbase site are only about style. IMO coding standards about api usage and ways of implementing code are much more important. A hacker's guide should only contain the most important ones of these. The todo is not only for the guide, but for the current online version too. > > Document everything > > =================== > > > > Every method, whether public or private, must start out with a > > documentation comment that describes what the method does. The > > documentation should mention every parameter received by > the method, > > every possible return value, and (if not obvious) the > conditions under > > which the method could return an error. > > Put the parameter names in the same case in the doc string > as in the > > method signature, > > I think it is often pointless to document a method which > implements a interface method, and I like the idea of simply > adding @inheritDoc in the javadoc only, or perhaps only type > // javadoc inherited (as I learned from code of RvM, which > also ensures that javadoc simply takes the doc of the parent. I like to use @see and refer to the method where the documentation is. > I also really dislike documentation which simply restates the > function's prototype. Docuemntation should add something, > otherwise it is only dissappointing. This is perhaps covered > by your words, but I'd like to stress it.. I had to put "If you are one of those developers who has a personal issue with documentation then at least document the public methods of your code" in the document, because it applies to me. Like you write, I hate documentation telling me what the method signature is telling me also. I hate inline documentation, bacause usually it means something is not clear in the code and a refactoring could solve it. If you refactor it and you still need a comment then refactor it again. If a comment is still required then just leave it there. Nico _______________________________________________ Developers mailing list [email protected] http://lists.mmbase.org/mailman/listinfo/developers
