| Here are some remarks concerning design and coding principles for the project. Please read them. It is much more efficient to get things right first than fix them afterwards. These remarks are of course only my point of you, if you believe there is room for discussion / improvement, your comments are welcome. S. |
Coding standards and recommandations for the Nuxeo ECM project
Introduction
I spent a few hours this week-end reading the 40 klocs of the Nuxeo 5 project, running code analysis tools and fixing some simple issues (but have not been able to address some of the most difficult ones, including cyclic dependencies or some synchronization problems).
The aim of this memo is to ensure that we focus on fixing these issues in the future earlier in the process, instead of spending time correcting them afterwards (or not at all).
It will be merged with what has already been written in the project’s coding standard:
- http://svn.nuxeo.org/trac/nuxeo/browser/doc/style.txt
- http://svn.nuxeo.org/trac/nuxeo/browser/ECMPlatform/NXCore/trunk/doc/ECMPlatform-Architecture.odt (section 4 - “Guidelines”)
Some issues that need your attention
Design
Use interfaces everytime it is possible instead of concrete classes
Ex: declare a variable or argument as a “Map”, not as a “HashMap”.
Why? Using interfaces make is possible to use several different implementations. Actually, interfaces are the basis of component-oriented programming.
But don’t overdo it if it’s not necessary.
Why? The more code we have, the more expensives maintainance is.
Avoid cyclic dependencies.
Why? This is a common design principle, called the “Acyclic Dependency Principle” or “ADP”.
How? use JDepend or a JDepend plugin for you IDE (ex: http://andrei.gmxhome.de/jdepend4eclipse/) or look at the JDepend report by Maven.
More info:
- http://chasethedevil.blogspot.com/2006/10/how-jdepend-changed-my-java-packaging.html
- http://clarkware.com/software/JDepend.html#cycles
- http://www.onjava.com/lpt/a/4489
- http://www.objectmentor.com/omReports/articles/Principles_and_Patterns.pdf (pages 18-22)
Unit tests
Write unit tests. (“If it’s not tested, it’s broken”)
Importance: high
How? Learn how to use JUnit. Use tests in existing modules as examples. Ask someone who knows.
Check that your unit tests have a coverage of most of the critical parts of your code.
Importance: medium
How? Look at the Cobertura report by Maven, or use the TPTP or EMMA (http://www.eclemma.org/) plugins for Eclipse or use the native code-coverage function of IDEA.
Use “assertEquals(constant, value)”, not “assertEquals(value, constant)”
Importance: low (cosmetic)
Use “assertNull(value)”, not “assertEquals(null, value)”
Importance: low (cosmetic)
Naming convention
Don’t use underscores (“_”) in variables, methods or class names.
Why? This is the Java convention.
Check some good articles on naming things, like:
- http://www.objectmentor.com/omReports/articles/naming.htm
It is especially important that we all use the same words (in case there an ambiguity) to refer to the same concepts (like “fetch” vs. “retrieve”, for instance).
Use modern Java features
Don’t use Hashtable (which is being deprecated), use HashMap (but there is something about synchronisation that needs to be clarified, I think).
Reference: http://leepoint.net/notes-java/data/collections/06overview.html
Use Java 5’s “foreach” construct instead of explicit iterators whenever possible.
Comments
Use comments to document that is not obvious.
Why? Otherwise, it will be harder for others (even you!) to maintain or extend your code. Some people may even end up refactoring your code under wrong assumptions.
Javadocs
Write javadocs according to the official Sun javadocs guidelines:
- http://java.sun.com/j2se/javadoc/writingdoccomments/
Why? Because Javadocs are compiled by a standard tool, you must conform to the syntax mandated by this tool.
Check that your javadocs provide useful information for third-party developers (or your teammates) by actually reading the generated doc.
How? See either “Project -> Generate Javadocs” from Eclipse, or “mvn site” and browse the docs.
Methodology tips
Here are a few points and tips to keep in mind.
Use a common standard
The coding standards I recommended previously are:
- http://www.ambysoft.com/essays/javaCodingStandards.html
- http://java.sun.com/docs/codeconv/
Use your IDE
Modern IDEs (+ adequate plugins, if necessary) include many code checking functions that help find out issues:
For Eclipse, use TPTP.
How?
- Use the Callisto update site to get the TPTP plugins.
- Right-click on your project, and select “Analysis”.
- Enable all the rules, and run the analysis on your module.
- Fix the issues that appear serious.
When you’re done fixing all the serious issues found by Eclipse TPTP, you may want to try out IDEA, which includes hundreds of checks, most of them useful.
How?
- Go to www.jetbrains.com and download an evaluation copy of IDEA 6.0.1.
- Run “Analysis” from the top menu.
- Fix the issues that appear serious.
Look at the Maven reports
Whithout using an IDE, it is still possible to get some reports using Maven.
Ex (for NXRuntime):
- http://maven.nuxeo.org/NXRuntime/checkstyle.html (obviously, and unfortunately, some of the reported “errors” are wrong, but many, if not most, are some violation)
- http://maven.nuxeo.org/NXRuntime/jdepend-report.html
Refactor
When something looks wrong in the code (“smell”), refactor it, but make sure you don’t break anything.
How?
- Check that the code you are refactoring is covered by some unit tests.
- Refactor. (Tip: a modern IDE (Eclipse and IDEA for instance) has some functions that may help.)
- Check that the code still compiles (including dependent modules) and all the unit tests are still passing, and commit.
Stuff to read
Here is a list of useful stuff to read:
ObjectMentor’s design articles at http://www.objectmentor.com/omReports/publishedArticles.html (click on “Design Principles”), the most important one being: http://www.objectmentor.com/omReports/articles/Principles_and_Patterns.pdf
“Common mistakes - Basic Design Principles”
- http://www.cs.huji.ac.il/~ood/lectures/OODX3_Design_Principles.ppt
Coding standards and recommandations for the Nuxeo ECM project ==============================================================
## Introduction I spent a few hours this week-end reading the 40 klocs of the Nuxeo 5 project, running code analysis tools and fixing some simple issues (but have not been able to address some of the most difficult ones, including cyclic dependencies or some synchronization problems). The aim of this memo is to ensure that we focus on fixing these issues in the future earlier in the process, instead of spending time correcting them afterwards (or not at all). It will be merged with what has already been written in the project's coding standard: - http://svn.nuxeo.org/trac/nuxeo/browser/doc/style.txt - http://svn.nuxeo.org/trac/nuxeo/browser/ECMPlatform/NXCore/trunk/doc/ECMPlatform-Architecture.odt (section 4 - "Guidelines") ## Some issues that need your attention ### Design 1. Use interfaces everytime it is possible instead of concrete classes. Ex: declare a variable or argument as a "Map", not as a "HashMap". Why? Using interfaces make is possible to use several different implementations. Actually, interfaces are the basis of component-oriented programming. 2. But don't overdo it if it's not necessary. Why? The more code we have, the more expensives maintainance is. 3. Avoid cyclic dependencies. Why? This is a common design principle, called the "Acyclic Dependency Principle" or "ADP". How? use JDepend or a JDepend plugin for you IDE (ex: http://andrei.gmxhome.de/jdepend4eclipse/) or look at the JDepend report by Maven. More info: - http://chasethedevil.blogspot.com/2006/10/how-jdepend-changed-my-java-packaging.html - http://clarkware.com/software/JDepend.html#cycles - http://www.onjava.com/lpt/a/4489 - http://www.objectmentor.com/omReports/articles/Principles_and_Patterns.pdf (pages 18-22) ### Unit tests 1. Write unit tests. ("If it's not tested, it's broken") Importance: high How? Learn how to use JUnit. Use tests in existing modules as examples. Ask someone who knows. 2. Check that your unit tests have a coverage of most of the critical parts of your code. Importance: medium How? Look at the Cobertura report by Maven, or use the TPTP or EMMA (http://www.eclemma.org/) plugins for Eclipse or use the native code-coverage function of IDEA. 3. Use "assertEquals(constant, value)", not "assertEquals(value, constant)" Importance: low (cosmetic) 4. Use "assertNull(value)", not "assertEquals(null, value)" Importance: low (cosmetic) ### Naming convention 1. Don't use underscores ("_") in variables, methods or class names. Why? This is the Java convention. 2. Check some good articles on naming things, like: - http://www.objectmentor.com/omReports/articles/naming.htm It is especially important that we all use the same words (in case there an ambiguity) to refer to the same concepts (like "fetch" vs. "retrieve", for instance). ### Use modern Java features 1. Don't use Hashtable (which is being deprecated), use HashMap (but there is something about synchronisation that needs to be clarified, I think). Reference: http://leepoint.net/notes-java/data/collections/06overview.html 2. Use Java 5's "foreach" construct instead of explicit iterators whenever possible. ### Comments 1. Use comments to document that is not obvious. Why? Otherwise, it will be harder for others (even you!) to maintain or extend your code. Some people may even end up refactoring your code under wrong assumptions. ### Javadocs 1. Write javadocs according to the official Sun javadocs guidelines: - http://java.sun.com/j2se/javadoc/writingdoccomments/ Why? Because Javadocs are compiled by a standard tool, you must conform to the syntax mandated by this tool. 2. Check that your javadocs provide useful information for third-party developers (or your teammates) by actually reading the generated doc. How? See either "Project -> Generate Javadocs" from Eclipse, or "mvn site" and browse the docs. ## Methodology tips Here are a few points and tips to keep in mind. ### Use a common standard 1. The coding standards I recommended previously are: - http://www.ambysoft.com/essays/javaCodingStandards.html - http://java.sun.com/docs/codeconv/ ### Use your IDE Modern IDEs (+ adequate plugins, if necessary) include many code checking functions that help find out issues: 1. For Eclipse, use TPTP. How? - Use the Callisto update site to get the TPTP plugins. - Right-click on your project, and select "Analysis". - Enable all the rules, and run the analysis on your module. - Fix the issues that appear serious. 2. When you're done fixing all the serious issues found by Eclipse TPTP, you may want to try out IDEA, which includes hundreds of checks, most of them useful. How? - Go to www.jetbrains.com and download an evaluation copy of IDEA 6.0.1. - Run "Analysis" from the top menu. - Fix the issues that appear serious. ### Look at the Maven reports 1. Whithout using an IDE, it is still possible to get some reports using Maven. Ex (for NXRuntime): - http://maven.nuxeo.org/NXRuntime/checkstyle.html (obviously, and unfortunately, some of the reported "errors" are wrong, but many, if not most, are some violation) - http://maven.nuxeo.org/NXRuntime/jdepend-report.html ### Refactor 1. When something looks wrong in the code ("smell"), refactor it, but make sure you don't break anything. How? - Check that the code you are refactoring is covered by some unit tests. - Refactor. (Tip: a modern IDE (Eclipse and IDEA for instance) has some functions that may help.) - Check that the code still compiles (including dependent modules) and all the unit tests are still passing, and commit. ### Stuff to read Here is a list of useful stuff to read: 1. ObjectMentor's design articles at http://www.objectmentor.com/omReports/publishedArticles.html (click on "Design Principles"), the most important one being: http://www.objectmentor.com/omReports/articles/Principles_and_Patterns.pdf 2. "Common mistakes - Basic Design Principles" - http://www.cs.huji.ac.il/~ood/lectures/OODX3_Design_Principles.ppt
-- Stefane Fermigier, CEO, Nuxeo SAS Open Source Enterprise Content Management (ECM) Web: http://www.nuxeo.com/ - Tel: +33 1 40 33 79 87 |
_______________________________________________ ECM mailing list [email protected] http://lists.nuxeo.com/mailman/listinfo/ecm
