Page History

...

Code Block

language	java

/**
 * This is Javadoc commenting for classes and interfaces.
 * Javadoc descriptions are full sentences.
 */
public interface fooFoo {
 
    /**
     * This is the format for Javadocs for public methods
     * and those defined by interfaces.
     *
     * @param param functions that take arguments have this
     * @return methods that return a value should indicate this
     */
    public boolean sampleMethod(Integer param);
}

...

Code Block

language	java

/**
 * Implementing classes should have Javadocs as well, to emphasize 
 * their function.
 */
public class fooImplFooImpl implements fooFoo {
	
	/**
     * Important variables and structures should also be 
     * commented so that it is picked up by Javadocs.
     */
	private static final int SAMPLE = 5;

    @Override
    public boolean sampleMethod(int param) {
        // classic one-liner
        boolean val = false;
        /*
         * Multi-line comments within the code may use this 
         * convention.
         */
        if (param < SAMPLE) {
            // FIXME: multiple lines may be commented like this
            // for code that may be removed or changed
            // return true;  
            val = true;
        }
        return val;
    }	
}

...

The logger should be private final, and associated with the particular class:

Code Block

language	java

import static org.slf4j.LoggerFactory.getLogger;
import org.slf4j.Logger;
...
private final Logger log = getLogger(getClass());
...
    /**
     * Checks if all the reachable devices have a valid mastership role.
     */
    private void mastershipCheck() {
        log.debug("Checking mastership");
        for (Device device : getDevices()) {

...

Checking for null method inputs - using checkNotNull():

Code Block

language	java

import static com.google.common.base.Preconditions.checkNotNull;
...
    @Override
    public void removeDevice(DeviceId deviceId) {
        checkNotNull(deviceId, DEVICE_ID_NULL);
        DeviceEvent event = store.removeDevice(deviceId);
        if (event != null) {
            log.info("Device {} administratively removed", deviceId);
            post(event);
        }
    }

toString() - ToStringHelper():

Code Block

language	java

import static com.google.common.base.MoreObjects.toStringHelper;
...
    @Override
    public String toString() {
        return toStringHelper(this)
                .add("id", id)
                .add("vlan", vlan)
                .add("ipAddresses", ips)
                .toString();
    }

Data structures such as Lists, ImmutableSet, and HashMultiMap

Unit testing - EqualsTester():

Code Block

language	java

import com.google.common.testing.EqualsTester;
...
VlanId vlan1 = VlanId.vlanId((short) -1);
VlanId vlan2 = VlanId.vlanId((short) 100);
VlanId vlan3 = VlanId.vlanId((short) 100);
 
// first two equality groups contain equal objects, last differs
// from constituents of first two groups
new EqualsTester().addEqualityGroup(VlanId.vlanId(), vlan1)
        .addEqualityGroup(vlan2, vlan3)
        .addEqualityGroup(VlanId.vlanId((short) 10));

...

Page tree

Versions Compared

Old Version 6

New Version 7

Key