Code Clarity - Comments, Preconditions and Postconditions Cmput Lecture 2 Department of Computing Science University of Alberta ©Duane Szafron 1999 Some code in this lecture is based on code from the book: Java Structures by Duane A. Bailey or the companion structure package Revised 12/16/99

©Duane Szafron About This Lecture In this lecture we will learn how to write Java code that is easy to understand, both as it is being written and later when it is being read.

©Duane Szafron Outline Comments Preconditions and Postconditions Assertions

©Duane Szafron Comments A comment is a an annotation that is added to program code that is ignored by the compiler and run-time system. For example: public class Ratio { /* an object for storing a fraction */ The first comment indicates that the code has been taken from the textbook. The second comment describes the purpose of the class. code based on Bailey pg. 8

©Duane Szafron Good Comments and Bad Comments A good comment is one that is cherished by a programmer for the clarity it brings. public class Ratio { /* an object for storing a fraction like 2/3 */ code based on Bailey pg. 8 A neutral comment is one that neither helps nor hinders the programmer. protected int numerator; // numerator of ratio A bad comment is one that confuses or inhibits the programmer. public class Ratio { /* this class is tricky: talk to Bob, it was his brainwave.*/

©Duane Szafron The Purpose of Comments A comment should describe what a program segment should do and under what circumstances it should do it (when). Comments should be created as soon as a designer or programmer knows the functionality of the segment being designed or implemented, not after! A comment allows a programmer to check for the desired functionality as the code is being written.

©Duane Szafron Sample Comment - What and When public class Ratio { /* an object for storing a fraction like 2/3 */ public Ratio(int top, int bottom) /* Initialize the receiver to be the fraction whose numerator is the top and whose denominator is the bottom. The bottom cannot be zero. */ what when code based on Bailey pg. 8

©Duane Szafron good name, no comment required Comment Granularity - variables poor name, comment required Should every variable declaration be commented? –If the name of a variable makes its purpose clear, it does not need a comment. –If the name does not make it clear, consider a better name rather than a comment. –The name “follows” a variable to all of its uses, the comment does not. protected int n; // numerator of ratio protected int numerator; code based on Bailey pg. 8

©Duane Szafron Comment Granularity - code lines 2 Should every line of code be commented? –If the names of variables and names of methods make the purpose clear, it does not need a comment. for (int i = 0; i < c; i++) l[++e] = s.l[s.s++]; for (int index = 0; index < count; index++) this.list[++this.end] = source.list[source.start++];

©Duane Szafron Comment Granularity - code lines 3 –If a line is still complex enough to need a comment, consider splitting it into multiple lines. for (int index = 0; index < count; index++) this.list[++this.end] = source.list[source.start++]; for (int index = 0; index < count; index++) { this.end++; this.list[this.end] = source.list[source.start]; this.start++; }

©Duane Szafron Comment Granularity - classes and methods Should every class be commented? –Yes! Should every method be commented? –Yes!

©Duane Szafron The Language for Comments Natural language is not very precise at describing program functionality. Natural language is also verbose. Mathematics is more precise, but not always as easy to understand. In this course, we will use a semi-formal notation called preconditions and postconditions for our method comments.

©Duane Szafron Preconditions A precondition tells when (under what circumstances) a method can be called: code based on Bailey pg. 8 public Ratio(int top, int bottom) /* Initialize the receiver to be the fraction whose numerator is the top and whose denominator is the bottom. The bottom cannot be zero. pre: bottom != 0 */

©Duane Szafron Postconditions A postcondition tells what a method must do: code based on Bailey pg. 8 public Ratio(int top, int bottom) /* Initialize the receiver to be the fraction whose numerator is the top and whose denominator is the bottom. pre: bottom != 0 post: constructs a ratio equivalent to top/bottom */

©Duane Szafron Method Comment Format The preconditions and postconditions form the comment for the method. code based on Bailey pg. 8 public Ratio(int top, int bottom) /* pre: bottom != 0 post: constructs a ratio equivalent to top/bottom */

©Duane Szafron Assertions An assertion is a statement about the state of your program that must be true. Preconditions and postconditions can be expressed as assertions. Some assertions may be represented as boolean expressions that can actually be evaluated when the program is run.

©Duane Szafron Checking Assertions at run-time In this course, we will use a class called Assert to check assertions. Four static methods are provided in this class: –pre(boolean, String) –post(boolean, String) –condition(boolean, String) –fail(String)

©Duane Szafron Assert Class static public void post(boolean test, String message) //pre: result of postcondition test //post: does nothing if test is true, otherwise // abort w/message code based on Bailey pg. 27 Public class Assert { static public void pre(boolean test, String message) //pre: result of precondition test //post: does nothing if test is true, otherwise // abort w/message

©Duane Szafron Assert Class - continued Public class Assert static public void condition(boolean test, String message) //pre: result of general condition test //post: does nothing if test is true, otherwise abort w/message static public void fail(String message) //post: throws error w/message } code based on Bailey pg. 27

©Duane Szafron Using the Assert Class public Ratio(int top, int bottom) { /* pre: bottom != 0 post: constructs a ratio equivalent to top/bottom */ Assert.pre(bottom != 0, "Denominator must not be 0"); this.numerator = top; this.denominator = bottom; } code based on Bailey pg. 8

©Duane Szafron Assertion Failure Example _exceptionOccurred: structure.FailedPrecondition ( Assertion that failed: A precondition: dr >= 0 or abs(dr) <= r) structure.FailedPrecondition: Assertion that failed: A precondition: dr >= 0 or abs(dr) <= r at structure.Assert.pre(Assert.java) at PolarPoint.transform(PolarPoint.java) at TestPlanarPoint.testTransform(TestPlanarPoint.java) at TestPlanarPoint.main(TestPlanarPoint.java)

©Duane Szafron Key Principle from the Textbook 5. Test assertions in your code. principles from Bailey ch. 2