The Coder's Handbook
Style and Comments
CODING STYLE
Formatting Your Code
A lot of the errors you will encounter early in your programming life will come from mistakes involving curly braces. Java is full of code that lives inside of code.
Some examples are:
Classes
Methods
Conditionals
Loops
Java doesn't actually care about how you indent code, or even if you put it on a new line. But you should care about making your code readable. If you can't read it clearly, you'll create hard to resolve bugs.
Consider the code examples below. Both are will compile and run, but one is a stylistic dumpster fire.
An Example of Proper Style:
public class GoodStyle
{
public static void main(String[] args)
{
Scanner sc = new Scanner(System.in);
int x = sc.nextInt();
while(x > 10)
{
if(x > 50)
{
x = x / 3;
}
else
{
x = x / 2;
}
}
System.out.println(x);
}
}
An Example of Bad Style
public class NightmareFuel{
public static void main(String[] args) { Scanner sc = new Scanner(System.in);
int x = sc.nextInt(); while(x > 10) {
if(x > 50) {
x = x / 3; } else {
x = x / 2;
}} System.out.println(x); }}
A Note on Curly Brace Placement...
Mr. M tends to put his curly braces on their own lines. This has pros and cons.
This helps make it clear how the braces pair up
It tends to reduce errors for beginning programmers
However, it does take up more vertical space.
It's also totally acceptable to put the starting one on the first line of a method, conditional, etc.
Good Style
public class Alpha
{
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
Also Good Style
public class Beta {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
COMMENT SYNTAX
Using Comments
A comment is a part of your program that doesn’t do anything; it’s a note for the reader.
This might not sound very useful at first, but you would be amazed at how quickly you’ll forget what you were thinking a day, week, or year ago.
A good rule of thumb to keep in mind is Eagleson's Law: "Any code of your own that you haven't looked at for six or more months might as well have been written by someone else."
There are two ways to add comments:
Using // makes any text after it on a given line a comment
Using /* and */ makes any text between it a comment.
Code:
public class Hello
{
public static void main(String[] args)
{
System.out.print("Hello World"); // hi there!
// this is also a comment
/* this is useful for
when you have a comment
that goes across many lines */
}
}
HOW TO COMMENT WELL
Readability and Memory
Sometimes comments can be used to help make your code clearer. This helps others read your code, and even helps you remember what you did a long time ago.
Some good example of comment usage in this way are:
Simple headings for blocks of code
Longer Explanations for very complex sections of code
Avoid Useless Comments
Be careful you don't write comments that aren't providing information to the user. The main goal should be to write clear code. It's safe to assume your reader knows Java.
This means that you should not write comments like:
public static void main(String[] args)
{
// This code prints out the message, "Hello World"
System.out.print("Hello World");
}
Debugging
Sometimes when you’re testing out code, you might want to disable a line of code. This is called commenting out the code. By turning code into a comment, you can "turn it off" for a bit without deleting it.
An easy way to do this for multiple lines in most editors is to select a bunch of code then hit CTRL-/ (control and forward slash). This will comment out all of these lines. Doing this again on a set of lines that contains only comments with un-comment that code.
RESOURCES