Lecture #19: Programming Style

November 16, 1999

Bob Pitha

bpitha@cs.ucsd.edu

http://www-cse.ucsd.edu/classes/fa99/cse5a

writing good programs

• There are many different qualities that define a “good” program

– it does what it’s supposed to

– it doesn’t crash

– it’s easy to use

– it’s fast and efficient

– it comes in a neat box

– it’s easy to maintain

– it’s easy to understand

writing good programs

• There are many different qualities that define a “good” program

– it does what it’s supposed to

– it doesn’t crash

– it’s easy to use

– it’s fast and efficient

– it comes in a neat box

– it’s easy to maintain

– it’s easy to understand

working vs. good

• You can write a program that works and is still not very good

– as you probably know by now, programming isn’t always easy

– it’s often not worth writing a program if you’ll only use it once

• so you will usually want to keep the program, and use it more than once

• you may need to fix bugs

• or add new features

• or give it to someone else to do those things to it

ugly code

• If you write ugly, unreadable code, nobody will be able to read it (nor will they want to)

– if you need to fix a bug, it can seriously affect how easy it is to find and fix

– if someone else looks at your code, they may make fun of you

example: bad code

$Text Box: #include <stdio.h> int main(void){int i,j;printf(“ “);for(j=1;j<= 10;++j)printf(“ %3d”,j);printf(“\n”);for(i=1 ;i<=10;++i){printf “%2d”,i);for(j=1;j<=10;++ j)printf(“ %3d”,i*j);printf(“\n”);}return 0;}$

example: silly code

$Text Box: #include <stdio.h> int main(void){int i ,j;printf(“ “);for(j= 1;j<=10;++j)printf(“ %3d” ,j);printf(“\n”);for(i=1;i <=10;++i){printf(“%2d”,i); for(j=1;j<=10;++j)printf (“ %3d”,i*j);printf (“\n”);}return 0;}$

why these are bad

• Here’s a broken version of the last one.

– It might take a long time to find the error

$Text Box: #include <stdio.h> int main(void){int i ,j;printf(“ “);for(j= 1;j<=10;++j)printf(“ %3d” ,j);printf(“\n”);for(i=1;i <=10;++i)printf(“%2d”,i); for(j=1;j<=10;++j)printf (“ %3d”,i*j);printf (“\n”);return 0;}$

what goes into a good program

• It’s readable

• It’s easily maintained

• It’s logically laid out

analogy to writing

• When you write something (say, a story or an article) you try to write well

– you want your readers to understand your point

– in fact, a good writer will write in ways that help make the point

• sentence length

• paragraph length

• word choice

• grammar

relevant quote

Text Box: “It is an old observation that the best writers sometimes disregard the rules of rhetoric. When they do so, however, the reader will usually find in the sentence some compensating merit, attained at the cost of the violation. Unless he is certain of doing as well, he will probably do best to follow the rules.
William Stunk and E. B. White,
The Elements of Style

what are elements of programming style?

• Naming

• Formatting

• Consistency

• Magic numbers

• Comments

Naming

what’s in a name?

• Labels something

– variable

– function

– other things we haven’t talked about yet

• Tells you its purpose

name qualities

• A good name should be:

– informative – it should tell you something

– concise – no longer than necessary

– memorable – you should remember what it is

– pronounceable – most people subvocalize

what are the issues?

• When you look at a declaration

– you should be able to guess what the variable is

– how it will be used

– supplemented by comments

• When you look at the code

– you shouldn’t have to keep referring back to the declaration

– the name should remind the user of the meaning

informative

• Depends on how close the usage will be to the declaration

– if it’s used very near the declaration, it’s not as important that the name carry as much information

– if the use and declaration are far apart, you want the name to be as informative as possible

• Examples:

– numberOfPoints vs. npoints

– elementIndex vs. index vs. i

concise

• Really long names are a pain

– lines get long and unwieldy

– numberOfItemsInList vs. listSize

• This gets tied up with the informative part

– more informative usually means longer

– try to avoid unnecessary length

memorable

• If all your names are similar, it doesn’t matter how informative they are

– the reader will still mix them up

– like reading a novel where there are 3 characters named “John”

pronounceable

• This seems silly, but unpronounceable names can really interfere with readability

• Don’t use weird abbreviations

– smrhshscrtch

– acimam

– rngcmf

– frnhtTmp

general idioms

• Active names for functions

– getTime()

– printTable()

– validateCoords()

• Nouns for variables

– numVertices

– capacity

accuracy

• If you change the code, be sure to change the names if necessary

– occasional inaccuracy is worse than generally meaningless names

Formatting

formatting?

• Good formatting can make a huge difference

– use spaces carefully

– indent lines to show structure

– use parentheses to resolve ambiguity

spaces

• In many cases, the compiler ignores spaces and tabs

– but the human eye is very se nsitive to spacing and distance

– things run together if there are no spaces

$Text Box: for(n=0;field[n]!=‘\0’;n++)$

$Text Box: for (n=0; field[n] != ‘\0’; n++)$

indenting

• We’ve already discussed this a little

• Indenting statement blocks can really help show your program’s structure

example

parenthesize

• The operator precedence and associativity rules remove ambiguity for the compiler