Why Your Java Code Needs Comments

06/15/2015

We’ve all been there. It’s five minutes before you have to leave for a party, errand, or appointment and you can’t find your keys. You know you put them in a ‘safe’ place, but you have no idea what or where that safe place was.

When writing code, you often times come up with great ideas to simplify your program, and make it easier to work with in the moment. The problem a lot of developers run into is when they go back a few days, weeks or months later to revise the program, or optimize it, but they can’t remember why their code was written a certain way. It's all of a sudden alien, and foreign.

Despite the amount of time time spent or the scale of a project, while writing a program’s logic taking a few minutes from time to time to write yourself notes can save you huge headaches down the road. Even the most talented developers will find themselves struggling to understand why a program was written a certain way, even if it was written by them.

By embedding your notes in your code when writing in Java you can put delimited blocks of text right in your source code. The notes text will be meaningful and useful to a human, but will be ignored and mean nothing to the compiler.

Here are three types of comments you can leave.

  1. Single-line comments

    A sinle-line comment spans, as the name suggests, only a single line. The comment is started with “//” and all text that follows is ignored by the compiler. A single-line comment is typically most useful for connoting the significance of a single line of code.


    6.15_image2
    Source: Jeff Friesen

  2. Multiline comments

    A multiline comment is typically used to give longer, more detailed information about larger sections of code. To begin a multiline comment type “/*” and to end the comment, use “*/”. All characters between the /* and */ will be ignored by the compiler and have adverse effects on your Java code.


    6.15_image3
    Source: Jeff Friesen


    Another use of multi line comments is removing lines of code from the compiler without having to delete them. So instead of deleting that code and losing it forever, or having to start a new document to save it, you can just block it out of the compiler’s view.


  3. Javadoc comments

    Javadoc comments are similar to multiline comments. They begin with “/**” and end with */. Just like with muliline comments and single-line comments, everything between the two symbols are completely ignored by the compiler.


    Here are a few examples of commonly used Javadoc tags:
    @author - identifies the source code’s author.
    @deprecated - identifies the method that should no longer be used in writing the source code.
    @param - identifies the parameters of the methods.
    @see - identifies a reference, or “see also”.
    @since - identifies the origin of the software’s initial release.
    @throws - identifies an exception that’s been thrown from a method.



Comments are integral part of any program. They help the person reading the code better and more quickly understand the intent and functionality of the program’s code.

Coding School Delaware inwilm JAVA JAVA Coding Academy nptech tech techjobs Why learn java Why use Java Wilmington

Comments