CodeStyle

Version 14.1 by Thomas Mortagne on 2009/05/14 12:52
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [dev:Community.CodeStyle.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Code Style

The XWiki project is following a specific coding style. We're using Checkstyle (checkstyle.xml) to ensure compliance of the code. Our build (the Maven2 one) is configured to fail on violations. However the decision to follow this code style and enforce it was only decided recently and the code base has not all been moved to this new code style. Hence:

  • We're only enforcing the code style in the code that have been moved to the new code style. The checked files are defined in xwiki/core/pom.xml (bottom of file).
  • We're asking new code to follow the new style and then once a Java file is compliant, to edit xwiki/core/pom.xml and add it there so that we cannot regress...

For examples of "clean" classes see the following classes and their unit tests:

Configuring your IDE to use the XWiki code style

Eclipse 3.x

Download codestyle-eclipse.xml.

After this, select Window > Preferences, and open up the configuration for Java > Code Style > Code Formatter. Click on the button labeled Import... and select the file you downloaded. Give the style a name, and click OK.

To reformat a file, press Ctrl+Shift+F while inside that file. To format only a portion of the file, select it and press the same key combination.

In recent versions of Eclipse (≥3.3) there is the possibility to configure Eclipse to automatically format a file when saving it. To do this, open Window > Preferences, select Java > Editor > Save Actions and enable Perform the selected actions on save and Format source code.

Download codetemplates-eclipse.xml.

After this, select Window > Preferences, and open up the configuration for Java > Code Style > Code Templates. Click on the button labeled Import... and select the file you downloaded. You can enable "Automatically add comments for new methods and types" if you want.

To generate a javadoc, press Meta+Shift+J while on the element you want to document.

IntelliJ IDEA 4.5+

Download codestyle-idea.xml.

Close IntelliJ IDEA. Place the file in your IntelliJ IDEA user configuration directory. For example for Windows Vista users of IntelliJ IDEA v6.x, it's in C:
Users
username
.IntelliJIdea60
config
codestyles
. Then open IntelliJ IDEA again, select File > Project Settings > Project Code Style, select Use per-project code style scheme, click on Import... and select XWiki.

Package names

All code that is not moved to the new XWiki Architecture based on components should use com.xpn.xwiki. New architecture code should use org.xwiki.

Interface best practices

Do not use 'public' in interfaces

Public is always implied in interfaces. Do not write:

public interface Page
{
   public String getParentSpaceKey();
}

But instead, write

public interface Page
{
    String getParentSpaceKey();
}

Javadoc Best Practices

We are following the Sun Javadoc coding conventions. Please make sure you're familiar with them when you write javadoc.

Write useful comments

Do not repeat name of method or any useless information. For example, if you have:

/**
 * @return the id
 */

public String getId()
{
   return this.id;
}

Instead, write:

/**
 * @return the attachment id (the id is the filename of the XWikiAttachment object used to construct this Attachment object)
 */

public String getId()
{
   return this.id;
}

Do not duplicate Javadoc

If you inherit from an interface then you shouldn't copy the Javadoc from the interface. Instead you should reference it. For example if getSomething() is the implementation a method defined in an inherited Something interface, you shouldn't write:

/**
 * Do something blah blah.
 */

public void doSomething()
{

[...]

Instead, write the following:

/**
 * {@inheritDoc}
 *
 * <p>Optionally add here javadoc additional to the one inherited from the parent javadoc.</p>
 *
 * @see Something#doSomething()
 */
public void doSomething()
{
[...]

Do not duplicate method comments with parameters comments

Instead of writing:

/**
 * Returns the key of the space to which this page belongs to.
 *
 * @return - Parent space's key as String.
 */

public String getParentSpaceKey();

Write:

/**
 * @return the key of the space to which this page belongs to. For example "Main".
 */

public String getParentSpaceKey();

Use version and since javadoc tags

For example:

/**
 * Something, blah blah...
 *
 * @version $Id: $
 * @since 1.6M1
 */

Do not use author javadoc tags.

Class/Interface names

  • Prefix class names with Abstract for abstract classes
  • Class names should start with an uppercase letter
  • Interface name should be as short and expressive as possible with no technical prefix or suffix. For example "Parser".
    • As a consequence interfaces shouldn't be prefixed with "I" (as in "IParser") or suffixed with "Interface" (as in "ParserInterface"), nor suffixed with "IF" (as in "ParserIF).
  • Classes implementing interfaces should extend the interface name by prefixing it with a characteristic of the implementation. For example "XWikiParser".
    • As a consequence implementation classes shouldn't be suffixed with "Impl", "Implementation", etc.
  • Default implementation classes where there's only one implementation provided by XWiki should be prefixed with "Default". As in "DefaultParser".

Package names

  • The package name for code using the component-based architecture must be of the format org.xwiki.(module name).*. For example org.xwiki.rendering.
  • Non user-public code must be located in an internal package. For example: org.xwiki.rendering.internal.parser.*
Tags:
   

Get Connected