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
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.
We follow the standard
Java coding conventions
published by Sun/Oracle. Please stick to these standards whenever writing code
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
* 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