Apr 20, 2023

Style

Why style matters

Good style isn’t just to make your code “look pretty” The most critical factor in style is readability If a program is readable,

It is easier to debug It is easier to maintain It is easier to upgrade

For “real” programs (those that actually get used), the time spent reading them far exceeds the time spent writing them

2

Two kinds of style

“Syntactic” style Mostly pretty mechanical: Spacing, indentation, capitalization, etc. Eclipse can do a lot of this for you Some more conceptual, for example, the names of methods should be

verbs Syntactic style is easier to define

“Semantic” style Largely or completely non-mechanical Rules are “slippery,” harder to describe and to apply Learned largely through experience

But only if you are willing to experiment and try new approaches Ultimately much more important than syntactic style

3

Syntactic style

5

Be consistent!

Most times, you will enter an ongoing project, with established style rules Follow them even if you don’t like them As they are what your team is used to, they will be more

readable to other members of your team

6

Do it right the first time

You only write code once, but you read it many times while you’re trying to get it to work Good style makes it more readable and helps you get it right!

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?

7

Indent nested code

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

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

The open brace always goes at the end of a line The matching close brace lines up with the statement being

closed Don’t use C-style braces unless that is the already established

standard for the project you are on Indentation should be consistent throughout the program

4 spaces is the standard for Java (other languages may differ)

8

Break up long lines

Keep your lines short enough to be viewed and printed Many people use 72 or 80 character limits Suggestions on where to break a long line:

It’s illegal to break a line within a quoted string Break after, not before, operators Line up parameters to a method Don’t indent the second line of a control statement with a

long test so that it lines up with the statements being controlled

9

Don’t use “hard” tabs

A hard tab is an actual tab character in your text It tells the program to go to the next tab stop (wherever

that is) Not every program puts tab stops in the same place

If you use hard tabs to indent, sooner or later your nice indentation will be ruined

Good editors can be set to use soft tabs (your tab characters are replaced with spaces) When you hit the tab key, the editor puts spaces into your

file, not tab characters With soft tabs, your indentation is always safe

10

Using spaces

Use spaces around all binary operators except “dot”: if (n > 1 && n % 2 == 1) n = 3 * n + 1;

Do not use spaces just within parentheses: if ( x < 0 ) x = -x; // don’t do this

Use a space before and after the parenthesized test in a control statement: if (x < 0) {...} while (x < 0) {...}

Do not use a space between a method name and its parameters; do put a space after each comma: int add(int x, int y) {...} a = add(3, k);

11

Use meaningful names

Names should be chosen very carefully, to indicate the purpose of a variable or method If the purpose changes, the name should be changed Spend a little time to choose the best name for each of your

variables and methods! Long, multiword names are common in Java

Eclipse will complete long names for you (control-space) However, if a name is too long, maybe you’re trying to use

it for too many purposes Don’t change the name, separate the purposes

Don’t abbreviate names But very common abbreviations, such as max for

“maximum”, are OK

12

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)); }}

13

Meaningful names: exceptions II

Local variables in methods 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 fields (class or

instance variables) or classes or methods

14

Meaningful names: exceptions III

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

15

Naming classes and interfaces

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

Use nouns to name classes: ExemptEmployee, CustomerAccount

Classes are supposed to represent things

Use adjectives to name interfaces: Comparable, Printable

Interfaces are supposed to represent features

16

Naming variables

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

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

17

Naming methods

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

Methods are capitalized the same as variables

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

18

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;

Constants are written in ALL_CAPITALS, with underscores between words

19

Correct (syntactic) style made easy

In Eclipse, go to Window Preferences Java Code Style Formatter, and under Select a profile: choose Java conventions [built-in]

Select some or all of your code and choose Source Format

To simply indent correctly, without reformatting, select some lines and choose Source Correct Indentation or just type ctrl-I.

Semantic Style

Think small

According to world-famous computer scientist Edgser Dijkstra, “We have small heads.” Translation: We can only keep track of a few things at a time

Small, single purpose methods are much easier to read, write, and debug Difficulty goes up with the square of the length of the method

Think of each method as a “verb” in a language you are inventing for this particular problem

Remember the acronym KISS: Keep It Simple, Stupid.

21

Design before you program

Good design, especially good choice of data structures, makes a huge difference in how difficult it is to write a program

For any given assignment, it is typical to see some submissions ten times as long as other submissions This probably means the student put in ten times as much

work The longer the program, the less likely it is to be correct

Good programmers usually consider at least two or three ways of doing the assignment before they start coding

22

Test first

You have to test anyway, so why not write the tests first?

TDD (Test Driven Design) leads to: Shorter, single purpose methods Methods that are testable Methods with a clearly defined function Methods that are more independent (i.e. you don’t have to set

up a lot of context before the method can be used) Better separation of concerns (for example, computation vs.

input/output) A good test suite greatly simplifies future maintenance

23

Keep it DRY (Don’t Repeat Yourself)

Don’t copy and paste code If you repeat a block of code, and the code needs to be

debugged or modified, you have to find every place that the code occurs

If different parts of a program all use the same code, errors in that code will be exposed and caught much earlier

The DRY principle also applies to data If you have two representations of the same information, they

must be kept consistent—this is extra work and error-prone Every bit of data should have a single “master”

representation; use methods to derive other views of that data

24

Refactor, early and often

Whenever you see a better way of doing things than you are currently doing them, refactor

Refactoring is modifying code without changing what it does, in order to make it simpler, cleaner, better

Refactoring is often necessary in order to add new functionality to a program

Here are the most common refactorings: Changing the name of a variable or method when you change what it does

(or just think of a better name) Extracting a chunk of code and making it a method (instead of copying

and pasting the code)

Eclipse makes many refactorings easy and (relatively) fairly safe Refactoring is a lot easier and safer if you have a good test suite

25

Comment

Write Javadoc comments for the person who is going to use your classes and methods

Tell them everything they need to know in order to use your code Don’t tell them how the code works (unless it’s absolutely required in

order to use the code—but this indicates a bad code design)

Write internal comments for the person who is going to maintain your code

Don’t repeat the obvious—assume they know some Java Explain tricky or obscure code

Better yet, replace tricky or obscure code with cleaner code

Your goal should always be for short, simple, self-explanatory code that doesn’t need comments

26

Do user testing

Sure, you think your user interface is simple and obvious—you wrote it! Sorry, but this is one area where your intuition simply cannot

be trusted Even user-interface experts get surprised

Getting even one person to try out your user interface will likely find 90% of the problems with it

27

28

The End

“Where a calculator on the ENIAC is equipped with 18 000 vacuum tubes and weighs 30 tons, computers of the future may have only 1 000 vacuum tubes and perhaps weigh 1½ tons.”

—Popular Mechanics, March 1949