If you have the best memory in the world, you might be able to remember everything you do, why you do it, how you do it, and when you do it. You may even be able to tell people about your experiences when you are near them. If that is the case, you are very much fortunate. However, what about when you’re not nearby? How will you and others remember what you did to get a line of code to work and what it’s supposed to do? Queue the computer.
Why Comments are Important & Useful
Computers are the best at remembering information you give it and sharing that information with others when you’re not around. The folks who designed Java put this principle to good use for the sake of efficient programming. Java allows you to make comments in your code to help you and your team remember what your code does. It is very useful for every bit of code that people may have a hard time understanding. The best part of comments is that they will not be compiled by the compiler. In other words, comments don’t affect the execution of your code. They are like thought bubbles.
Your goal as a programmer is to write clean, effective, and human understandable code. Comments will help you more easily accomplish writing human understandable code. As you get better at coding and begin building large projects with complex algorithms, you will want to make extensive use of comments to later remember what your code does and be able to easily and effectively explain it to others. This is great coding style.
Let’s see what kind of comments are available for us to employ in our code.
Single Line Comments
Single line comments, like the one above, allow you to write quick comments to explain bits of code as you go. These comments are great for explaining your variables and their declarations. Single line comments must start with double forward slashes
// and can only span a line of code. Let’s refer to our bank account example from the Datatypes chapter to see how we can make use of single line comments for variables:
Single line comments are great for commenting little bits of code when there’s not much to explain. However, when you write larger code, it’s best to use multi-line comments. Multi-line comments allow you to write long comments that can span for multiple lines by starting with “/*” and ending with “*/”. Imagine you are writing a program to represent an ATM and you want to let the user use the ATM as long as they don’t type “EXIT”, you’d want to clearly explain how you intend to do that in your code. Doing so will require multiple lines, but it will also allow you to get all of your thoughts across:
Notice how we used multiple lines to explain our while-loop which does a lot of work. This will help us and others who read our code better understand what is happening.
Don’t worry if you don’t yet understand what’s going on in that code snippet due to the while loop and Scanner. We’ll go over those concepts soon. For now, play around with the supporting code to see how it works.
This was originally published on Dec 18, 2015.