Apr 18, 2023

Style

Consolidated Lectures

2

About the book

This book is a team effort by many good programmers, not just one person’s opinions

The rules have been widely distributed and commented upon

The rules reflect widespread and accepted practices

And no, I don’t agree with everything in the book!

3

Rule 1: Adhere to the style of the original

Consistent style is very important Most times, you will enter an ongoing project, with

established style rules Follow them even if you don’t like them Don’t try to establish “better” style rules

It won’t work anyway There may be reasons you don’t know about

If a project has mixed styles with no consistency, you might try to get people to agree on one

4

Rule 3: Do it right the first time

You’re working on a large project, so you use good style...

...but you need a tool to help you do one little job, so you slap it together quickly

Guess which program will be around longer and used by more people?

5

Rule 5: Indent nested code

Always indent statements that are nested inside (under the control of) another statement

if (itemCost <= bankBalance) { writeCheck(itemCost); bankBalance = bankBalance - itemCost;}

while (seconds > 0) { System.out.print(seconds + "..."); seconds = seconds - 1;}

Indentation should be consistent throughout the program 2 to 4 spaces is usually about right

6

Rule 6: Break up long lines

Scrolling a window horizontally is a pain! When you print on standard paper, long lines are either

cut off or wrap in bad places I have long used a 72 character limit Some editors will show you a limit line The book provides good advice on how to break up

long lines (read it!)

7

Rule 8: Don’t use “hard” tabs

Once upon a time, you could depend on tab stops every eight character positions

Today, every editor has its own idea of where and how to set tab stops

If you change editors, your nice indentation gets ruined It’s worse if you use both tabs and spaces I have learned this one the hard way!

A hard tab is an actual tab character in your text Good editors can be set to use soft tabs (your tab

characters are replaced with spaces) BlueJ uses only soft tabs

8

Rule 9:Use meaningful names

Names should be chosen very carefully, to indicate the purpose of a variable or method

If the purpose changes, the variable or method should be renamed

It is worthwhile spending a little time choosing the best name

Long, multiword names are common in Java

9

Rule 10: Use familiar names

Where common terminology exists, use it; don’t make up your own

Example from the book: If your users refer to “customers,” your program should use the name Customer, not Client

10

Rule 11: Question excessivelylong names

Variables should be used for a single purpose Methods should do one simple, clearly defined thing If a descriptive name is overly long, maybe the

variable or method is trying to serve too many purposes

11

Meaningful names: exceptions I

It is common practice to use i as the index of a for-loop, j as the index of an inner loop, and k as the index of a third-level loop

This is almost always better than trying to come up with a meaningful name

Example: for (int i = 1; i <= 10; i++) {

for (int j = 1, j <= 10; j++) { System.out.println(" " + (i * j)); }}

12

Meaningful names: exceptions II

Method variables may be given short, simple names, if: The purpose of the variable is obvious from context, and The variable is used only briefly, in a small part of the

program But never use meaningless names for class or instance

variables

13

Rule 28: Use standard names for “throwaway” variables

If variables have no special meaning, you can use names that reflect their types For example, if you are writing a general method to work

with any strings, you might name them string1, string2, etc.

Alternatively, you can use very short names s, t, u, or s1, s2, etc. are often used for Strings p, q, r, s are often used for booleans w, x, y, z are often used for real numbers

14

Rule 12: Join the vowel generation

Despite the cutesy name, this rule is important In more primitive languages, names were often limited

to 8 or so characters This led to names like maxVolum and lngPlyng The usual rule was to leave out vowels, starting from the right Such names are harder to read and to remember

Do not leave out vowels, or otherwise use unusual abbreviations, in Java!

15

Naming classes and interfaces

Rule 18: Capitalize the first letter of each word, including the first: PrintStream, Person, ExemptEmployee

Rule 19: Use nouns to name classes: ExemptEmployee, CustomerAccount Classes are supposed to represent things

Rule 20: Use adjectives to name interfaces: Comparable, Printable Interfaces are supposed to represent features

16

Naming variables

Rule 25: Capitalize the first letter of each word except the first: total, maxValue

Rule 26: Use nouns to name variables: balance, outputLine Variables are supposed to represent values

17

Naming methods

Rule 22: Capitalize the first letter of each word except the first: display, displayImage

Methods are capitalized the same as variables

Rule 23: Use verbs when naming methods: displayImage, computeBalance Methods are supposed to do something

18

Rule 13: Capitalize only the first letter in acronyms

In names, write acronyms such as GUI and API as Gui and Api

Examples: setDstOffset, displayAsHtml, loadXmlDocument

Since capital letters are used to separate names, this rule helps avoid confusion

Sun’s APIs don’t always follow this convention

19

Naming constants A constant is an identifier whose value, once given,

cannot be changed Constants are written with the keyword final, for

example: final int FIVE = 5; final float AVOGADROS_NUMBER = 6.022E23;

Rule 31: Constants are written in ALL_CAPITALS, with underscores between words

Exception: color names, such as Color.pink Colors were defined before conventions were established However, Java 1.4 adds properly capitalized names for

colors, such as Color.PINK

20

Kinds of comments

“Standard” (C-style) comments: /* ... */ One-line and end-line comments:

// a one-line comment is on a line by itselfx = 0; // an end-line comment follows code All of the above are “internal” comments, seen only by

someone looking at your code Internal comments are only for maintainers But avoid things that would embarrass you to a user!

Documentation (javadoc) comments: /** ... */ These are meant to be seen by the entire world! Documentation comments are not covered in this series

of slides

21

Which kind of internal comment?

Rule 36: Use “standard” (/*...*/) comments to comment out code without removing it. This is a quick way to comment out and uncomment code

This rule isn’t actually appropriate for us BlueJ’s comment and uncomment commands make it

easier to use one-line (//...) comments Standard comments cannot be nested, so it’s tricky

commenting out code with comments One-line comments don’t have this problem

22

Explaining the code I

Rule 59: Add internal comments only if they will aid in understanding your code. Don’t repeat the javadoc comments Don’t put in comments to explain things that are obvious

from the code Don’t put in irrelevant or useless comments // Go Cubs!!!! Always put /* ... */ comments before the code they

describe, never after the code

23

Explaining the code II

Rule 37: Use one-line comments to explain implementation details. One-line comments are also good for writing reminders for

yourself about things you still need to work on // These assertions should be replaced by

Exceptions I like to use one-line comments to tell what the next several

lines of code are going to do // Put this Vehicle in a random location

24

End-line comments I

Rule 61: Avoid the use of end-line comments. This rule is largely to prevent overly long lines

But Rule 62 says: Explain local variable declarations with an end-line comment. int edgeDistance; // distance to the nearest edge

And Rule 64 says: Label closing braces in highly nested control structures. } // end switch

} // end if } // end for j} // end for i

Better yet, avoid highly nested control structures

25

End-line comments II

I also find end-line comments useful for an else that is a long way from its if: if (distance > 5) {

... a lot of code in between ...}else { // distance <= 5 ...}

But now that we have assert statements, this is even better: ...

else { assert distance <= 5;

26

Flagging unresolved issues

Rule 63: Establish and use a set of keywords to flag unresolved issues. I personally like to use $$

// $$ the canvas isn't being redrawn properly More specific flags are likely to be used in large projects

// $$ DLM: Problem #1403; Level: Urgent

27

Intentionally missing break

Rule 65: Add a “fall-through” comment between two case labels of a switch statement, if no break statement separates those labels. The switch statement is so badly designed that forgetting the

break is a common error To keep an intentionally missing break from being

“corrected,” add a comment

28

Label empty statements

Sometimes you intentionally use a loop with an empty statement body

Rule 66: Label empty statements. while ((c = reader.read()) == space) ;

// Empty body This is because the semicolon is small and easy to

overlook I prefer a different solution: use an empty block as

the statement body while ((c = reader.read()) == space) { }

29

Don’t repeat the code

Rule 60: Describe why the code is doing what it does, not what the code is doing.

Another way of saying this is:Comments should not echo code. Here’s a typical example of a bad comment: count = 0; // set count to zero

You should assume that anyone reading your internal comments knows some Java!

30

Use the active voice

Rule 34: Use the active voice, and omit needless words // zero out the array // each of the elements of the array is set to

// zero by the following loop Writing comments is still writing--all the rules for

good writing apply to comments Best reference: The Elements of Style, by Strunk

and White

31

Debugging statements

We sometimes put in debugging statements that we plan to remove afterwards

Simple trick: start these “temporary” statements in the first column, so you can find them easily

boolean legalLocation(int row, int col) {System.out.println("In legalLocation: " + row + " " + col); return row >= 0 && row < numRows && column >= 0 && column < numCols; }

32

The End

33

The End