• 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 FooBarException if 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
/**
 * Sample showing how a proper Javadoc comment should look like.
 */
  • No labels