Intro to CS – Honors I Documentation and Coding Style

1. Intro to CS – Honors IDocumentation and Coding Style Georgios Portokalidis gportoka@stevens.edu

2. Picking Good Names Not helpful Self-documenting double radius; double area; public static final PI = 3.14159; Area = PI * radius * radius; • double r; • double a; • a = 3.14159 * r * r;

3. 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

4. More Comments  More Readable Poor comment Useful comment double radius; //in inches double area; //in square inches • double radius; //the radius of a circle Useful for people that use the metric system. http://www.wired.com/thisdayintech/2010/11/1110mars-climate-observer-report/

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

6. 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 = 3.14159 * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } } Program structure elements

7. Indentation Without proper indentation things can get ugly quickly. 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 = 3.14159 * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } }

8. 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 = 3.14159 * 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

9. Indentation • 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. 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 = 3.14159 * radius * radius; System.out.println("A circle of radius " + radius + " inches"); System.out.println("has an area of " + area + " square inches."); } }

10. Using Named Constants public class CircleCalculation2 { public static final double PI = 3.14159; 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?

11. Javadoc