Week 7 [Mon, Mar 2nd] - Topics

JavaDoc is a tool for generating API documentation in HTML format from comments in the source code. In addition, modern IDEs use JavaDoc comments to generate explanatory tooltips.

/**
 * Returns an Image object that can then be painted on the screen.
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument.
 * <p>
 * This method always returns immediately, whether or not the
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives
 * that draw the image will incrementally paint on the screen.
 *
 * @param url An absolute URL giving the base location of the image.
 * @param name The location of the image, relative to the url argument.
 * @return The Image at the specified URL.
 * @see Image
 */
public Image getImage(URL url, String name) {
    try {
        return getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        return null;
    }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

In the absence of more extensive guidelines (e.g., given in a coding standard adopted by your project), you can follow the two examples below in your code.

A minimal JavaDoc comment example for methods:

/**
 * Returns lateral location of the specified position.
 * If the position is unset, NaN is returned.
 *
 * @param x X coordinate of position.
 * @param y Y coordinate of position.
 * @param zone Zone of position.
 * @return Lateral location.
 * @throws IllegalArgumentException If zone is <= 0.
 */
public double computeLocation(double x, double y, int zone)
    throws IllegalArgumentException {
    // ...
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

A minimal JavaDoc comment example for classes:

package ...

import ...

/**
 * Represents a location in a 2D space. A <code>Point</code> object corresponds to
 * a coordinate represented by two integers e.g., <code>3,6</code>
 */
public class Point {
    // ...
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed?’ Improve the code and then document it to make it even clearer. _{-- Steve McConnell, Author of Clean Code}

Some think commenting heavily increases the 'code quality'. That is not so. Avoid writing comments to explain bad code. Improve the code to make it self-explanatory.

Do not repeat in comments information that is already obvious from the code. If the code is self-explanatory, a comment may not be needed.

//increment x
x++;

//trim the input
trimInput();

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

# increment x
x = x + 1

# trim the input
trim_input()

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Write comments targeting other programmers reading the code. Do not write comments as if they are private notes to yourself. Instead, One type of comment that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.

// a quick trim function used to fix bug I detected overnight
void trimInput() {
    ....
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

/** Trims the input of leading and trailing spaces */
void trimInput() {
    ....
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def trim_input():
"""a quick trim function used to fix bug I detected overnight"""
    ...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

def trim_input():
"""Trim the input of leading and trailing spaces"""
    ...

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Comments should explain the WHAT and WHY aspects of the code, rather than the HOW aspect.

WHAT: The specification of what the code is supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct.

/** Removes all spaces from the {@code input} */
void compact(String input) {
    input.trim();
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

WHY: The rationale for the current implementation.

// Remove spaces to comply with IE23.5 formatting rules
compact(input);

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

HOW: The explanation for how the code works. This should already be apparent from the code, if the code is self-explanatory. Adding comments to explain the same thing is redundant.

// return true if both left end and right end are correct
//    or the size has not incremented
return (left && right) || (input.size() == size);

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

boolean isSameSize = (input.size() == size);
return (isLeftEndCorrect && isRightEndCorrect) || isSameSize;

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Combining parts of a software product to form a whole is called integration. It is also one of the most troublesome tasks and it rarely goes smoothly.

Build automation tools automate the steps of the build process, usually by means of build scripts.

In a non-trivial project, building a product from its source code can be a complex multistep process. For example, it can include steps such as: pull code from the revision control system, compile, link, run automated tests, automatically update release documents (e.g., build number), package into a distributable, push to repo, deploy to a server, delete temporary files created during building/testing, email developers of the new build, and so on. Furthermore, this build process can be done ‘on demand’, it can be scheduled (e.g., every day at midnight) or it can be triggered by various events (e.g., triggered by a code push to the revision control system).

Some of these build steps such as compiling, linking and packaging, are already automated in most modern IDEs. For example, several steps happen automatically when the ‘build’ button of the IDE is clicked. Some IDEs even allow customization of this build process to some extent.

However, most big projects use specialized build tools to automate complex build processes.

Some build tools also serve as dependency management tools. Modern software projects often depend on third party libraries that evolve constantly. That means developers need to download the correct version of the required libraries and update them regularly. Therefore, dependency management is an important part of build automation. Dependency management tools can automate that aspect of a project.

An extreme application of build automation is called continuous integration (CI) in which integration, building, and testing happens automatically after each code change.

A natural extension of CI is Continuous Deployment (CD) where the changes are not only integrated continuously, but also deployed to end-users at the same time.

See Git-Mastery → Lesson T9L3. Merging Pull Requests

See Git-Mastery site → Lesson: T10L2. Forking Workflow (with Branching)

See Git-Mastery site → Lesson: T10L1. Git Workflows

Feature branch workflow is similar to the forking workflow except there are no forks. Everyone is pushing/pulling from the same remote repo. The phrase feature branch is used because each new feature (or bug fix, or any other modification) is done in a separate branch and merged to the master branch when ready. Pull requests can still be created within the central repository, from the feature branch to the main branch.

As this workflow require all team members to have write access to the repository,

• it is better to protect the main branch using some mechanism, to reduce the risk of accidental undesirable changes to it.
• it is not suitable for situations where the code contributors are not 'trusted' enough to be given write permission.

The centralized workflow is similar to the feature branch workflow except all changes are done in the master branch.