Development Best Practices

This document explains the best practices and conventions that should be followed when writing code, documentation and samples for Apache Synapse. It is mainly intended for Synapse committers who directly commit code into the Synapse code base. It is also a useful resource for potential contributors who are willing to write code for Synapse.

Committers are highly encouraged to follow the guidelines mentioned in this document whenever adding a new source file to the code base or when modifying an existing source file. Same best practices should be followed when committing a patch provided by a contributor.

This document is a work in progress. We will continue to make this more detailed and comprehensive as we go along. So stay tuned for updates.

Contents

Writing Code

  • We follow the standard Java coding conventions published by Sun/Oracle. Please stick to these standards whenever writing code for Synapse.
  • The maximum number of characters in a single line should not exceed 120. Please configure your IDE to properly enforce this restriction on all source files.
  • All source files should contain the following license header at the top.
    /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */
  • Pay attention to indentation and proper spacing between code blocks.
  • Each Java source file should have a introductory Javadoc comment describing its main purposes and features.
  • Every public method should have a Javadoc comment describing its purpose and behavior. When writing Javadoc comments for methods, input arguments, return values and checked exceptions should also be clearly explained.
  • Use meaningful names for all classes, interfaces, methods and variables. Pay attention to spellings. Code should be easier to follow and understand.
  • Feel free to include comments within the code to explain non-trivial logic.
  • When removing a public method or an API, first deprecate the relevant operations by applying the proper Javadoc annotations. Actual removal of the operation should be done after some time, in a future release.
  • Write test cases for each new feature and bug fix implemented in the code base. Test cases make it easier to check for regressions and keep the code base healthy at all times.

Writing Samples and Documentation

  • All documentation files and samples should we well-formed XML documents.
  • We use the Maven XDoc plugin to generate Synapse documentation and website. Please take some time to go through the documentation of the XDoc plugin and learn and its features. In pariculay, you should learn the XDoc documentation format and use the standard XDoc tags over HTML whenever possible.
  • Any XML code samples included in the documentation should be properly HTML encoded and indented. Such code samples should go in a HTML 'div' section withe the class 'xmlConf'.
    <div class="xmlConf"> ... Encoded XML content ... </div>
  • Attempt to keep each line shorter than 100 characters. This is bit tricky to enforce when writing XML/HTML content. But try to stick to the rule whenever possible.
  • Add navigation links wherever possible. When describing a particular feature add a link to the relevant sample.