How to use Comment and Examples in java

When learning a programming language, comment is the first item known.

Engineers and those who have just started learning may know that comment notes have nothing to do with programming.

However, even if you know how to write comments, some of you have never thought about the proper way to write comments.

I will tell you about the critical points of writing comments on this post.

I hope you will find it helpful as you stand at the entrance to the engineering profession.

1 What is the comment?

1. Use as a memo
2. Debugging with Comments Out

2 Points to keep in mind when writing comments

1. Comments that describe what you are doing are unnecessary
2. Write why the code is the way it is
3. Write down known bad points
4. Make the likely failures known
5. Make rules for comments

3 Summary

1 What is the comment?

A comment is a note in the source code. Whether there are comments or not does not affect programming behavior.

For example, in Java, the following notation is used.

1 2 3 4 5

public class Main {      public static void main(String args[]) {         // comment      } }

For basic knowledge of comments, check the following.

Single-line and Multi-line Comments in Java
Java has a comment function as well, and if you enclose a single line with [//], or multiple lines with [/*] and [*/], it will be treated as a comment

There are two primary uses for comments.

1 Use as a memo

When programming, you probably write code with a severe mind about that system. A lot of helpful information is swirling around in your head.

However, once you have been away from the system for six months, you will find that you have a lot of helpful information swirling around in your head. You will be surprised how little you remember.

When I look at the source code after a long time, I often wonder what I was thinking back then. It is a waste of time.

Imagine if you were to hand over the work to someone else, not just yourself. There will be no information left except the code in front of you. There may be a design document left, but it is too big a picture to be helpful.

That's why comments are used as notes to make the program code easier to read by adding various annotations.

According to a survey conducted by a research organization, 19% of source code is commented. 

2 Debugging with Comments Out

The other use is to make some of the code into comments so that it no longer works as programming.

Commenting out code to make it inactive is called comment out.

By commenting out a portion of code at a time, it is possible to see where errors occur. Often, an entire function is commented out to check it.

I will tell you the points of the former when used as a memo on this post.

2 Points to keep in mind when writing comments

Comments should be simple and not too many.

The more comments you make, the longer it takes to read the source code. Also, too many comments describe making the code very difficult to read.

Often, comments can be confusing, even though they are meant to be helpful.

Therefore, write only as many comments as are necessary.

1 Comments that describe what you are doing are unnecessary

The most common comment I see is code that describes what the code is doing.

For example, I frequently see comments such as "output to the screen here" or "handle errors if the value is null."

"Are these comments necessary?"

In most cases, it is easy to tell by reading the code, aside from the more complex issues. The following comments are meaningless.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

public class Main {     public static void main(String args[]) {           //Generate calendar         Calendar cal = Calendar.getInstance();           //Set format and output         SimpleDateFormat sdf = new SimpleDateFormat("[1] y/M/d");         System.out.println(sdf.format(cal.getTime()));           //change format         sdf.applyPattern("[2] yyyy/MM/dd");         System.out.println(sdf.format(cal.getTime()));      } }

The English written directly in the source code is meaningless and requires twice as much effort because you have to read both the English and the code.

You can write them as notes for yourself while a beginner, but they are not helpful comments in the workplace.

2 Write why the code is the way it is

What others who see the source code want to know most is the "why" of the code.

For example, if you have written a cumbersome process, the question is, "Why did you choose this source code?" is known only to the person who wrote it.

//This is a roundabout process, but I did it because it was.

//I think there was a better way to write it, but I didn't fix it because of the time issue.

Why is this source code in this state?　It is helpful to write the answer first in the section where the question "What is the answer?" is expected."

If you don't, there might be a reason. This is because it would be difficult to handle the problem.

In many cases, the "what" of what is being done can be found by reading the source code. However, the "why" is often unclear even if you read the source code.

Try to write the "Why" as much as possible. However, if the code is complicated, it does not hurt to write "What."

3 Write down known bad points

It takes courage to be stingy with the code you have written, but it is better to write it down well before you forget.

// Fix it because it's too much work here.

// Need to change to a faster algorithm.

// Error handling is too rough. It Needs to split it up.

If you write things such as "I'm sorry, I'm sorry," it will be easier to make corrections when you have more time, and the next person who sees it may correct it.

Inevitably, system construction tends to be a race against time. It would be nice to do it perfectly, but it doesn't always work out ideally.

At the very least, you should make the problem "visible" by leaving comments like these.

4 Make the likely failures known

It is also essential to make the likely failures known.

Let's assume that the following is the case.

MAX_CAPACITY_MB = 100;

There is a possibility that there will be a need to increase the capacity to 150 MB later on. 

However, it may not be that the user originally wanted to increase the ability to 100 MB, but rather that the upper limit was set to 100 MB due to a server-side problem.

In such a case, you can write a comment as shown below to indicate that the server-side needs to be improved first to raise the upper limit. 

// Server-side upper limit
MAX_CAPACITY_MB = 100;

5 Make a rule for comments

When developing with a team, it is easier to make rules for comments.

For example, the following notation can be used.

• TODO: ・・・ There is a task to do later
• FIXME: ・・・ There is a defect
• XXX: ・・・ There is a big problem

If the team all knew these, comments could be shortened, and reminders would be easier to give.

Summary

Comments are not programs, but they are equally essential artifacts.

Try to write them carefully, thinking of them not as "just something" but as a reminder to others and your future self.

The day will surely come when you will be thanked by those around you and your future self.

Java Book for Beginner

Head First Java, 2nd Edition

created by Digital Nomad Book

Head First Java

• Amazon

The most important selling points of Head First Java is its simplicity and super-effective real-life analogies that pertain to the Java programming concepts. 

It is also the best book to learn java and start your learning journey with Java Development. 

Head First Java covers almost all OOPS concepts and fascinatingly explains them. 

Despite several readers claiming it to be a dated book, as it covers nothing beyond Java 5.0, Head First Java is still found on the shelves of numerous Java veterans.

Thus, it is a must-have book for every Java pursuer and developer.