Coding Chica

Be nice to your future self. Add comments to your code as you go. I like to imagine that I will be called out at 2am to investigate an issue in the code I’m writing. What will I need in the future to be able to quickly recall what I was thinking when I first wrote this code? Well-documented code is an investment for future you…or your team if you find another opportunity and leave the team.

There are 3 styles of comments you will see in Java files:

Single-Line Comments

Single-line comments can be a partial or full line. They are in effect until the line ends.

// This is a single line comment.  The compiler will ignore the remainder of this one line.

private String firstName; // This is also a single-line comment.

Block Comments

Block comments have specific start (/*) and end (*/) designations because they may span multiple lines, if desired. Often, you will see continuing lines in the comment prefixed with * for easier reading, but that need not be the case. For example:

/*
This is a block style comment.
*/

/*
 * This is also a block style comment.
 */ 

/* This is a block style comment on one line. */

Javadoc Comments

A Javadoc is specialized documentation file that describes a class / package and all the publicly available methods and constants within them. As they are read and used by an application to generate other documentation, they must follow a specialized format

We will circle back to these more later. For now, what you should be aware of is that they also have specialized start (/**) and end (*/) designations and can be defined for: fields, methods, classes, or packages.

/** 
 * This is a class-level Javadoc comment.  
 * It describes the class as a whole.
 */
public class App {
    /**
     * This is a field-level javadoc comment.  
     * It describes only this variable / field and any expectations 
     * for data to be stored in this field.
     */
    private String userFirstName;


    /**
     * This is a method-level javadoc comment.
     * It describes only this method's behavior when invoked.
     */
    public String getUserFirstName() {
...