CIT 590 Programming suggestions
Spring 2010 , David Matuszek

This repeats some of the things I said in class.

Functions should be short and single-purpose

In a recent program, I wrote 13 functions. The average length of a function, not counting comments, was 5.23 lines. The two longest functions (to encode a letter pair, and to decode a letter pair) were each 14 lines. Sometimes you need longer functions, but this isn't an unusual case.

If you have a function that works and does something useful, don't add more code to it; write another function.

If you have a function that takes several steps to do something, and you put in comments to say "now do this," consider whether you could instead turn those steps into single functions.

Use Test-Driven Design

Seriously. It works.

Don't start by testing whether the program as a whole works; these should be the last tests you try to get running. They are the top-level tests that you need to work toward.

One of the really nice things about TDD is that it lets you make steady, continuous progress. The next time you spend an hour trying to debug a 15-line function, think about this.

Here's a really short summary of TDD you should look at.

Avoid magic numbers

Some of you are using magic numbers like 97 in your program. Seriously, are you going to remember next week what this number is? If someone else looks at your program, will they know? If you really need to change a character to a number (you probably don't), do something like ord('a') instead of 97.

It's pretty much always okay to use the numbers 0 and 1. In a Sudoku program I wrote, I used 3 and 9, because I thought it was obvious what those numbers refer to; however, I later realized that it was possible to create a hexadecimal Sudoku (16 rows and columns, and 16 4x4 boxes), or one based on any other square number.

Write comments

One reason for writing comments is that English is still, in most cases, easier to read than code. If someone wants to use your function or your class, they can more easily do so if you tell them in English what it does. Another reason is to aid in debugging and updating. It's usually easier to figure out what a function is doing if you start by knowing what it is supposed to do.

Good, self-explanatory names for functions and variables can help a lot, but they aren't always enough. It's easy enough to remember what your methods do when you are first writing the program, but your memory won't be as good a few weeks or months later.

Finally, keep comments up to date with changes in the code. Incorrect comments are much worse than no comments at all.

Programming hints

Communicate with your partner! Email, instant messaging, phone calls, whatever. Sitting together at one computer is best, but I realize you can't always do that. Come as close as you can.

Also, remember that the best way to learn is to teach.

The more you can rely on built-in methods, like lower() and isalpha(), the less code you have to write and debug. The Python Standard Library is your friend.

You can pass as many parameters as you like into a function, but a function can only return one value. Right? Right. But that value can be a tuple! For example,

def chopTwoCharacters(message):
    return (message[:2], message[2:])
This can be called as
(twoLetters, restOfMessage) = chopTwoCharacters(message)
or even as
twoLetters, restOfMessage = chopTwoCharacters(message)

I don't use this actual function in my program, but I use the idea. It's very useful!

Here's a Really Bad Idea: One partner writes the tests and the other partner writes the functions. I know this is a bad idea because some of my past students have tried it. Besides, it completely negates the value of TDD.

Do not make a last-minute change to your program--not even adding a comment!--just before you submit it. If you change even a single character, test it again before you submit it. This is always good advice, but this year, for the first time, you only get to submit once. If you mess it up, we have to discard your submission before you can submit again.