# Week 7
## Documentation Tools
### Javadoc
- **Javadoc is a tool for generating API documentation in HTML format from doc comments in source.** In addition, modern IDEs use JavaDoc comments to generate explanatory tool tips.
- An example method header comment in JavaDoc format:

/**
 * 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;
        }
 }

Generated HTML documentation:
- 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 {
  ...
}

- 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{
    //...
}

### Markdown
- Markdown is a lightweight markup language with plain text formatting syntax.

## Code Quality: Code Comments
- Improve the code to make it self-explanatory.
- If the code is self-explanatory, refrain from repeating the description in a comment just for the sake of 'good documentation'.
- One type of comments that is almost always useful is the header comment that you write for a class or an operation to explain its purpose.
- Comments should explain **what and why** aspect of the code, rather than the how aspect.
- **What** : The specification of what the code supposed to do. The reader can compare such comments to the implementation to verify if the implementation is correct
- **Why** : The rationale for the current implementation.
- **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.

## SDLC Process Models: Basics
- Software development goes through different stages such as **requirements, analysis, design, implementation and testing**. These stages are collectively known as the **software development life cycle** (SDLC).
- There are several approaches, known as *software development life cycle models* (also called software process models) that describe different ways to go through the SDLC. Each process model prescribes a "roadmap" for the software developers to manage the development effort. The roadmap describes the aims of the development stage(s), the artifacts or outcome of each stage as well as the workflow i.e. the relationship between stages.
- **The *sequential model*, also called the *waterfall model*, models software development as a linear process**, in which the project is seen as progressing steadily in one direction through the development stages.
- When one stage of the process is completed, it should **produce some artifacts** to be used in the next stage.
- The major **problem** with this model is that **requirements of a real-world project are rarely well-understood at the beginning and keep changing over time**.
- **The *iterative model* (sometimes called iterative and incremental) advocates having several iterations of SDLC.** Each of the iterations could potentially go through all the development stages, from requirement gathering to testing & deployment. Roughly, it appears to be similar to several cycles of the sequential model.
- In this model, **each of the iterations produces a new version of the product**.
- The iterative model can take a **breadth-first or a depth-first approach to iteration planning**.
- **breadth-first**: an iteration evolves all major components in parallel.
- **depth-first**: an iteration focuses on fleshing out only some components.
- **Most project use a mixture of breadth-first and depth-first iterations.**

## Continuous Integration/Deployment
- **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.**
- **Some build tools also serve as dependency management tools.**
- 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.**

## RCS: Workflows
- **In the *forking workflow*, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.**
- **RCS can be done in two ways: the *centralized way* and the *distributed way*.**
- **Centralized RCS** (CRCS for short)**uses a central remote repo that is shared by the team**. Team members download (‘pull’) and upload (‘push’) changes between their own local repositories and the central repository. Older RCS tools such as CVS and SVN support only this model. Note that these older RCS do not support the notion of a local repo either. Instead, they force users to do all the versioning with the remote repo.
- **Distributed RCS** (DRCS for short, also known as Decentralized RCS) **allows multiple remote repos and pulling and pushing can be done among them in arbitrary ways.** The workflow can vary differently from team to team. For example, every team member can have his/her own remote repository in addition to their own local repository, as shown in the diagram below. Git and Mercurial are some prominent RCS tools that support the distributed approach.