code clarity - comments, preconditions and postconditions cmput 115 - lecture 2 department of...

Code Clarity - Comments, Code Clarity - Comments, Preconditions and Preconditions and PostconditionsPostconditions

Cmput 115 - Lecture 2Cmput 115 - Lecture 2

Department of Computing ScienceDepartment of Computing Science

University of AlbertaUniversity 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 1999

2

About This LectureAbout 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.


3

OutlineOutline

Comments

Preconditions and Postconditions

Assertions


4

CommentsComments

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


5

Good Comments and Bad CommentsGood 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 */


• 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.*/


6

The Purpose of CommentsThe 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.


7

Sample Comment - Sample Comment - What and WhenWhat 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 fractionwhose numerator is the top and whosedenominator is the bottom.The bottom cannot be zero.

*/

what

when



8

good name, nocomment required

Comment Granularity - Comment Granularity - variablesvariables

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;



9

Comment Granularity Comment Granularity - code lines 2- 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++];


10

Comment Granularity Comment Granularity - code lines 3- 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++;

}


11

Comment Granularity Comment Granularity - classes and methods- classes and methods

Should every class be commented?– Yes!

Should every method be commented?– Yes!


12

The Language for CommentsThe 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.


13

PreconditionsPreconditions

A precondition tells when (under what circumstances) a method can be called:



Initialize the receiver to be the fractionwhose numerator is the top and whosedenominator is the bottom.The bottom cannot be zero.pre: bottom != 0

*/


14

PostconditionsPostconditions

A postcondition tells what a method must do:



Initialize the receiver to be the fractionwhose numerator is the top and whosedenominator is the bottom.pre: bottom != 0post: constructs a ratio equivalent to top/bottom

*/


15

Method Comment FormatMethod Comment Format

The preconditions and postconditions form the comment for the method.



pre: bottom != 0post: constructs a ratio equivalent to top/bottom

*/


16

AssertionsAssertions

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.


17

Checking Assertions at run-timeChecking 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)


18

Assert ClassAssert 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


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


19

Assert Class Assert Class -- continuedcontinued

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

}



20

Using the Assert ClassUsing the Assert Class

public Ratio(int top, int bottom) {/*

pre: bottom != 0post: constructs a ratio equivalent to top/bottom

*/

Assert.pre(bottom != 0, "Denominator must not be 0");this.numerator = top;this.denominator = bottom;

}



21

Assertion Failure ExampleAssertion 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)


22

Key Principle from the TextbookKey Principle from the Textbook

5. Test assertions in your code.

principles from Bailey ch. 2

code clarity - comments, preconditions and postconditions cmput 115 - lecture 2 department of...

Documents

sample comment

neutral comment

int numerator code

java code

line of code

program code

code clarity comments

int index