Adding Comments to Source Code in Java

Encoder Denso QR Bar Code in Java Adding Comments to Source Code

One of the first attempts at explaining how a program worked was by making the source code more understandable by using high-level languages, like BASIC or Pascal, to create self-documenting code So rather than try to decipher cryptic code like

SECTION text global main main: mov eax,4; write system call mov ebx,1 mov ecx,msg mov edx,len int 0x80 mov eax,1 system call mov ebx,0 int 0x80

You could replace the preceding assembly language commands with a shorter, more descriptive high-level language command like this:

PRINT It s alive!

Such self-documenting code helps explain what a single line of code does, but doesn t necessarily tell you how the entire program works as a whole or what problem the program even solves Rather than rely on self-explanatory language commands, programmers started adding explanations directly into the source code itself by using comments A comment is nothing more than text, embedded in the source code To keep the compiler from thinking a comment is an actual command, every comment needs a special symbol in front of the comment, such as

REM This is a comment in BASIC This is another comment in BASIC // This is a comment in C++ and Java # This is a comment in Perl and Python ; This is a comment in LISP and assembly language

Comments allow you to write short explanations, directly in the source code, that describe what the source code does Looking at the following code, can you understand what it does

C = SQRT(A * A + B * B)

Deciphering this code is straightforward This command multiplies two variables by themselves, A and B, adds the results together, and finds the square root of the sum, which gets stored in the C variable However, knowing how the command works doesn t tell you what or why this code is doing this By adding comments to the source code, you can explain this, as follows:

Calculates the hypotenuse of a triangle (C) using the Pythagoras theorem: C2 = A2 + B2 C = SQRT(A * A + B * B)

Even if you don t know (or care) about Pythagoras theorem, the comments help you understand what the command is calculating Some programmers use comments to insert jokes, profanity, or remarks about their co-workers directly in their source code Just be aware that other people besides you may need to look at your source code So if you ve laced your program with profanity-ridden tirades against your co-workers, don t be surprised if one of your co-workers finds and reads the comments you made about him, which could be humorous or embarrassing You can put comments anywhere in a program because the compiler ignores them anyway The two types of comments are line comments and block comments

Line comments appear directly on a line that already contains a command like this:

The problem with line comments is that they can make source code somewhat harder to read That s why some programmers prefer putting comments on separate lines like this:

Calculates Pythagoras theorem C = SQRT(A * A + B * B)

Comments exist purely for other people to read, so it doesn t matter whether you put them on a line with a command or on a separate line To make comments easier to read, use plenty of blank lines and spaces The following example looks crowded:

Calculates the hypotenuse of a triangle (C) C = SQRT(A * A + B * B) Calculates Pythagoras theorem

By adding blank lines and extra spaces, you can make each comment easier to find and read:

Calculates the hypotenuse of a triangle (C) C = SQRT(A * A + B * B) Calculates Pythagoras theorem