Intro to CS – Honors I Documentation and Coding Style GEORGIOS PORTOKALIDIS

Picking Good Names NOT HELPFUL double r; double a; a = * r * r; SELF-DOCUMENTING double radius; double area; public static final PI = ; Area = PI * radius * radius;

Comments // comment text ◦Everything after “//” is ignored by the compiler /* comment text */ ◦Everything between “/*” and “*/” is ignored by the compiler ◦Appropriate for multi-line comments /** comment text*/ ◦Same as above, but also understood by Javadoc Use comments to explain details

More Comments  More Readable POOR COMMENT double radius; //the radius of a circle USEFUL COMMENT double radius;//in inches double area;//in square inches Useful for people that use the metric system.

Comment Your Code import java.util.Scanner; /** Program to compute area of a circle. Author: Jane Q. Programmer. Address: Programming Assignment 2. Last Changed: October 7, */ public class CircleCalculation { public static void main(String[] args) { double radius; //in inches You can also place this block above imports

Indentation public class CircleCalculation { public static void main(String[] args) { double radius; //in inches Scanner keyboard = new Scanner(System.in); System.out.println("Enter the radius of a circle in inches:"); radius = keyboard.nextDouble(); area = * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } Program structure elements

Indentation public class CircleCalculation {public static void main(String[] args) { double radius; //in inches Scanner keyboard = new Scanner(System.in); System.out.println("Enter the radius of a circle in inches:"); radius = keyboard.nextDouble(); area = * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } } Without proper indentation things can get ugly quickly.

Indentation public class CircleCalculation { public static void main(String[] args) { double radius; //in inches Scanner keyboard = new Scanner(System.in); System.out.println("Enter the radius of a circle in inches:"); radius = keyboard.nextDouble(); area = * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } Indent every new block of code

Indentation public class CircleCalculation { public static void main(String[] args) { double radius; //in inches Scanner keyboard = new Scanner(System.in); System.out.println("Enter the radius of a circle in inches:"); radius = keyboard.nextDouble(); area = * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } Quite a few “schools” of coding styles Example: spaces vs tabs Use one or the other! When using spaces use an indentation of 4 or 8 spaces Tab can be configured to leave these many spaces.

Using Named Constants public class CircleCalculation2 { public static final double PI = ; public static void main(String[] args) { double radius; //in inches double area; //in square inches Scanner keyboard = new Scanner(System.in); System.out.println("Enter the radius of a circle in inches:"); radius = keyboard.nextDouble(); area = PI * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } Can be also placed here. What would be the problem with that?

Javadoc