Coding Convention

Code style

The source and JavaDoc of Dubbo follow below specifications:

• Code Conventions for the Java Programming Language
• How to Write Doc Comments for the Javadoc Tool

Exception and Logging

• Log more context information as possible, such as error reason, error server address, client address, registry center address, dubbo version and so on.
• Try to put the main cause at the front, and display all other context information with key-value paris after it.
• Log is not printed where the exception is thrown, log level is determined by the final exception handler, and must print log when dicarding exception.
• ERROR log means NEED TO ALARM, WARN log means COULD AUTO RECOVERY, INFO long mean NORMAL.
• Suggestion: config ERROR log in Monitor center for real-time alarm, summary and send WARN log weekly.
• RpcException is the ONLY external exception of Dubbo，all internal exceptions mush be transfered to RpcException if need to throw out to user.
• RpcException CAN NOT have sub-class, all types of information are identified with ErrorCode in order to keep compatible.

Configuration and URL

• Use initials and camelCase for multiple words for object properties ¹.
• Use lowercase and split by ‘-’ for multiple words for config properties ².
• Use lowercase and split by ‘.’ for multiple words for URL properties ³.
• Use URL transfer parameters as possible, Don’t define Map or other types, config information also transfer to URL style.
• Minimize URL nesting to keep URL simplicity.

Unit testing and integration testing

• Use JUnit and EasyMock for unit testing, use TestNG for integration testing, use DBUnit for database testing.
• Don’t put large integration test case in unit testing for running speed of unit test case.
• Use try...finally or tearDown to release resource for all test cases of unit testing.
• Minimize test case that with while loop which need waiting repsonse, use to make the logic in timer as function for timer and net testing.
• For fail-safe testing, unified use LogUtil assertion log output.

Extension point base class and AOP

• AOP class should be named as XxxWrapper，Base class should be named as AbstractXxx.
• Use AOP for combine relationship between extension points, ExtensionLoader only loads extension points, including AOP extension.
• Try to use Ioc inject dependency of extension points, Don’t direct dependent on factory method of ExtensionLoader.
• Try to use AOP implement the common action of extension points, instead of using base class, such as the isAvailable checking before load balancing, which is independent of load balance. Close the URL paramters which no need to check.
• Use base class for abstaction for a variety of similar types, such as RMI, Hessian 3rd protocols which have generated interface proxy, only transfer interface proxy to Invoker to complete bridging, and public base class can do the logic.
• The base class is also part of the SPI, and each extension should have a convenient base class support.

Module and packaging

• Base on reusability for packaging, dividing the interface, base class and large implementation into separate modules.
• Put all interfaces under the base package of module, and put base classes in support subpackage, different implementations are placed under the subpackage named by extension point.
• Try to keep subpackage dependent on parent package, NOT reverse.