The following are the coding standards and best practices that need to be adhered to when contributing to the Apache Stratos code base:

Comments 

  • Add Java doc comments
    • Always add doc comments for classes and methods/functions. For more information, see Adding Java doc comments in the IDE.
    • Explain each and every parameter, return type and assumption.

  • Add line comments

    • In the event you have a complex logic, explain the logic and the rationale behind doing things.

Formatting Code

  • The IDE will provide suggestions to clean your code and improve the format of your code. Ensure to go through each of the suggestions and adhere to it provided it is applicable.
    For example: 
    • In intelliJ IDEA these comments appear in yellow, blue etc. next to the scroll bar. 
    • In Eclipse these comments will be listed under the Markers tab.

Logging

When logging, ensure to follow the guidelines below:

  • Make sure to create logs (e.g., info logs, debug logs etc.) whenever applicable, so that it will be useful in the future.

  • Log with ample local information and context

  • Keep in mind that the logs are for users. Therefore, make the logs meaningful, readable and also make sure to run a spell checker (e.g., Ispell)

  • Use correct log levels. For example, do not log errors as warnings or vice versa.

  • Always remember to log the error before throwing an exception

  • Follow the standards below when logging:
    • Use square brackets to separate objects. 
      For example: 
      [network-partition] network-partition-1 [cluster-instance] single-cartridge-app-1 [cluster] php1.php.domain
    • When logging an object, make sure to override with the toString() method of the respective class.
    • Make sure to use the same naming convention to identify defined types.
      For example: 
      [network-partition]
    • Declare all loggings in the String.format as it allows string pooling, gives clarity and readability.
    • Use isDebugEnabled() and isInfoEnabled() guard conditions when debug logs are being added.
    • When logging, include all the relevant information available on a given log.
    • Avoid indicating generic log entries. For example, if a debug or info entry requires a certain operation to be done, it must be indicated as about to be done and not be indicated as being done or done.

Logic

  • Make sure that your code is readable.

  • Use meaningful variable names as compilers can handle long variable names.

  • Declare the variable in the respective locality. Be cautious when declaring public variables.

  • In Java code the underscore character should only be used when declaring constants, and should not be used anywhere else.

  • Make sure the function/method names are self descriptive

  • Explain a function/method using a single sentence without conjunctions. Therefore, and/or is not allowed in the description. The following will help you abide by this guideline:

    • Make sure to address each concern separately

    • Check if you do multiple things in a function

    • Too many parameters is generally an indication that something is wrong

  • Use variables to capture the status and return the status  at the end whenever possible.

  • Avoid statuses being returned from multiple places as this will make the code less readable.

  • Be consistent in managing the state. For example, initialize the state of the method to FALSE and set it to TRUE when the state changes. 

  • Have a comment at end of each "if" block after the closing bracket. 

  • Use "if" statements rationally and ensure the behavior is homogeneous.

  • When a collection is returned, you need to return an empty collection and not null (NULL).

  • Do not use interfaces to declare constants. Use a final class with public static final attributes and a private constructor.

  • Always use braces to surround code blocks ({}) even if it is a single line. 

  • Break code into multiple lines if it exceeds 100 columns.

  • Always align method parameters, exceptions etc. to improve readability. The latter mentioned can be done using the settings in your IDE. 

  • If you write a method to handle an exception, handle it appropriately and then throw it to another method if needed.

  • Do not use string literals in the code, instead declare constants and use them. Constant names should be self descriptive.

  • Before declaring a constant check (especially in base libs such as, Axis2) if someone has already declared it. Thereby, whenever possible use constants that are already defined. 

Java Specific

  • Run FindBugs on your code.

    You should run FindBugs on your new code or modified code, and commit only after fixing any bugs reported. It is recommended to use the intelliJIDEA (FindBugs-IDEA) or the Eclipse FindBugs plugin.

Adding Java doc comments in the IDE

In the IDE type /** and press enter to add Java doc comments. This will automatically generate the outline for block comments relevant to the method or class.

Example doc comment format for a method
/**
    * Explain what this method does
    * @param a1 Explain about argument a1
    * @param b1 Explain about argument b1
    * @return Explain what will get returned when this method is executed
    */
   public boolean test(String a1, String b1) {
      boolean status = false;
       return status;
   }
Example doc comment format for a class
/**
* Explain what this class does
*/

public class A{
   
}
  • No labels