- Always ensure that you have the right license headers in place !
- when creating new types please use just the CURRENT year - don't set/copy stuff like This file Copyright (c) 2003 - 2011 Magnolia International
- Class-level documentation is mandatory.
- since we moved to git we don't use @version $Id$ any longer - simply because git doesn't support itè
- we don't use @author tags any longer as we're usually not interested in the one who had create the file (SCM could tell
you if required)
- @author can however be added as a "recognition" mark for external contributors
- @deprecated must include since: e.g. @deprecated since 4.0
- First sentence of any Javadoc comment must finish with punctuation. (This is/was needed for summary pages/tables to include the first sentence next to the described element)
- All javadoc comments will start with a "/**" line, then have lines "* My great comment or empty" and will end with "*/". We don't use one line javadocs (/** My great comment. */).
- DRY: Don't Repeat Yourself. Don't add a
@throws FooBarExceptionif there is no relevant explanation as to why/how the exception is thrown. That only adds noise and duplicate what we already know (by the method signature). Same goes for all other tags in method javadoc.
- See http://dev.magnolia-cms.com/~gjoseph/on-code-readability