Hello! If you reached this page it (probably) means that you are Juliano's CSCI 1110 student, so welcome!
In this page you will find code examples of the coding guidelines you should follow in CSCI 1110.
This page serves as an informal guide for examples on how to organize and comment your code in the course
This guide exists to provide structure to students. Why? There isn't a specific rule-set (although there are minimal standards) on how you should write your Java code. My goal with this guide is to select one writing style for students so there is no guessing game.
Your code will always start with a comment (JavaDoc) explaining who the author of the code is (including banner number) and a description of the class (what is this class/program doing). You must write the description using your own words and not copy it from the assignment's description.
Part of your marks on the assignments will be related to these guidelines. If you follow them you will get full marks on the Code Clarity part of the assignments.
You will ensure that your code has proper indentation (more on this further down), is properly commented, and respects the 80-character limit on each line (you can thank IBM for that). The 80-character limit makes it easier to read your code without the need of horizontal scrolling. If you are using IntelliJ, it shows a solid line on the 80-character mark.
You must fully comment your code. You can use both inline comments, multi-line comments, and JavaDocs. Please assume that the person reading your code is familiarized with coding; avoid comments explaining Java's syntax.
Comments should be indented to the same level as the code they are commenting.
//You can use double slash (//) for single line comments
//Read and store the user's age so we can calculate the discount
int userAge = kb.nextInt();
/*
* You can use multi-line comments too!
* Start with a slash star.
* Every single line after will be a comment until
* you close it with star slash
*/
You must choose fully qualified names for your variables, methods and classes. For example, we should be able to
understand what is your variable storing by its name. Same goes for methods and classes.
public class Bicycle {
private String brandName;
private int currentGear;
private double currentSpeed;
private int currentCadence;
public Bicycle(String brandName){...}
public boolean changeGear(int gear){...}
}
public class cycle {
private String name;
private int g;
private double spd;
private int c;
public cycle(String n){...}
public boolean newGear(int g){...}
}
In Java, we use curly brackets ({ and }) to delimit code blocks and scope (similar to : in python).
Java lets you omit the curly brackets if there is only one line after in a code block (such as an if statement).
WarningYOU MUST ALWAYS USE CURLY BRACKETS
Warning
You can choose to leave the opening curly bracket on the same line or add it to a new line, it is up to you. My personal recommendation is that you keep on the same line. Chose one style and use it throughout your code consistently!
if(javaIsCool){
}
if(javaIsCool)
{
}
You must indent your code (with 4 spaces OR 1 tab). The rule is fairly straightforward: every time you start a new
block with { you must increase the indentation. Every time you close a code block with },
you must reduce the indentation. Simple, eh?
public class SumExample{
public static void main(String[] args){
int sum = 0;
for(int i = 0; i < 10; i = i + 2){
sum += i;
}
System.out.println(sum);
}
}
public class SumExample{
public static void main(String[] args){
int sum = 0;
for(int i = 0; i < 10; i = i + 2){
sum += i;
}
System.out.println(sum);
}
}
public class SumExample{
public static void main(String[] args){
int sum = 0;
for(int i = 0; i < 10; i = i + 2){
sum += i;
}
System.out.println(sum);
}
}
You will use JavaDoc comments to document your classes and methods. JavaDoc comments can be used later to create webpages
or PDFs with the documentation of your code. We will not generate those files in CSCI 1110.
JavaDoc comments start similar to multi-line comments. The difference is one extra star (*) on the first line. You start it
with /** and finish it with */. You annotate your comments with tags that start with @
You will use one comment block for each class you create. The first text in the class comment is a description (in your own words)
of the class. After the description, you can add any relevant tags. There are several tags you can use but you are only required to use one for classes:
@author. Use the author tag for your name and your banner number
/**
* This class represents a bicycle with a set amount of gears.
* Objects from the bicycle's class will also keep track of their
* current velocity and current gear.
*
* @author Juliano Franz - B00XXXXXX
*/
public class Bicycle {...}
Methods will start in a similar fashion as the classes. The first part of the comment is a description of the method. Then, you will add
one @param tag for each parameter variable of the method (or no tag if there aren't any parameters) and one @return
explaining the return value of the method. If the method does not return anything (e.g. void) then you should omit @return.
If your method throws an exception, you should also add the @throws tag.
/**
* Method used to change the current gear of the bicycle. If the gear passed as an argument
* is outside the range of the bicycle's cassette the method will return false.
* @param gear the gear we want to switch to. Must be greater than zero and less than maxGear
* @return true if the new gear was withing the range of the cassette; false otherwise
*/
public boolean changeGear(int gear){...}
/**
* Getter for the current speed of the bicycle. Values are always greater than zero
* @return the bicycle's current speed as a double.
*/
public double getCurrentSpeed(){...}
In object-oriented programming you use Constructors to create objects from your classes. Constructors have the same name of class. In Java, you can overload constructors. Here are some good guidelines regarding constructors for you to follow:
this keyword.
public class Employee {
public static int serialCardNumbers = 0;
private String name;
private int cardNumber;
//Using String for the department is not the best solution...
private String department;
public Employee(String name, int cardNumber, String department){
this.name = name;
this.cardNumber = cardNumber;
this.department = department;
}
public Employee(String name, String department){
this(name,serialCardNumbers,department);
serialCardNumbers++;
}
public Employee(String name){
this(name, "Undefined");
}
}
When comparing booleans do not use equals true or false. Compare the variable directly if you are testing for true
or negate the variable (with !) if you are testing for false
if(haveCash){
System.out.println("Pay the man");
}
if(haveCash == true){
System.out.println("Pay the man");
}
if(!haveCash){
System.out.println("Run from the man");
}
if(haveCash == false){
System.out.println("Run from the man");
}
Chose your variable types based on what you are trying to store. For example, if you are trying to store numbers that will never have decimal points
use ints instead of doubles.
We will use double as data type for floating point in Java not float.
public static void printHelloWorld(){
System.out.print("Hello World");
}
public static void printHelloWorld(){
//for(...){
// if(...){
// ....
// }
//}
System.out.print("Hello World");
}
Any part of code that is not yours MUST be cited. Place a comment above the code that you want to cite its source.
/* The following code was taken from
* URL: http://www,stackoverflow.com/.....
* Retrieved on February 30, 2020
* Author: Linus Torvalds
*/
…
/* Cited Code Ends */