Commenting Conventions

##Javadoc Comments When you write code, you will be using this format for writing comments. It is very similar to C style commenting, and it gives a good overview of the what each function does. ##Javadoc Example ###Starting Code Let us start with an example of a basic clamp function. The initial function could look something like this:

public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
}

If you submit a function that looks like this, YOU WILL BE SKINNED ALIVE!!!

Description

Start a multiline comment above the function that includes a description of what the function does.

/**
 * Clamps a number between 1 and -1 for motor purposes.
 */
public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
}

Parameters

Use the @param message to describe each parameter of the function.

/**
 * Clamps a number between 1 and -1 for motor purposes.
 * @param    num    Number to be clamped.
 */
public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
}

Return Values

Use the @return message to describe the return value:

/**
 * Clamps a number between 1 and -1 for motor purposes.
 * @param    num    Number to be clamped.
 * @return   The input number clamped between 1 and -1.
 */
public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
}

References and Author (optional)

Use the @author message with your name if you authored the class or the name of the original author. Also, you can use @see to reference other non-primitive classes.

/**
 * Clamps a number between 1 and -1 for motor purposes.
 * @author   Tux the Penguin
 * @param    num    Number to be clamped.
 * @return   The input number clamped between 1 and -1.
 * @see      CustomDouble
 */
public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
}

Other Comments

The only other mandatory comment is, at the end of each function, you should put a one-line comment including the name and parameters of the function that you just wrote (for ease of use).

/**
 * Clamps a number between 1 and -1 for motor purposes.
 * @author   Tux the Penguin
 * @param    num    Number to be clamped.
 * @return   The input number clamped between 1 and -1.
 * @see      CustomDouble
 */
public CustomDouble Limit(CustomDouble num) {
    if(num>1) return 1;
    else if (num<-1) return -1;
    else return num;
} // End Limit(CustomDouble num)

Finally, it is not mandatory but recommended that, within functions, you describe what your code is doing with one-line comments as frequently as necessary.

Remember: Well-commented code makes programming easier and more enjoyable for everybody!