Programming Style - Generic

This page contains some default/generic recommendations for good programming style. Many programming languages have specific conventions that should be followed, but you should at least follow the guidelines on this page. Check with your instructor on whether they have any additional requirements.

Note that all of these help your code be more readable/understandable and should also reduce the number of mistakes you make. An example file which follows all of these guidelines - multiply.py.

Variable names

Use meaningful names. You can use i, n, j, k, x, y for integers or numbers if you only have a few of these in your program. The more different variables you are using, the more important that you use a descriptive name.

Function names

Use good names for functions that describe what they are doing.

Variable and function names

You can choose whether to use camelCase or underscores for variable and function names that consist of multiple words. Example in camelCase - countEvenLines. Example with underscores - count_event_lines. You should choose one of these and be consistent.

Function comments

Right before a function include a brief description of what it does, what the parameters are supposed to mean, if there is a return value what it means, and anything else someone would need to know to be able to call your function properly.

Using functions

Break your code into smallish separate tasks that can each be solved with a function. You should not have more than about 20 lines of code in each function, and your main program that uses the functions should not be more than about 20 lines of code. Another way to think of the length of a function is that it should fit on one screen.

If your program needs to be do basically the same task multiple times, put that task into a function that is called when needed. If you find yourself copy'ing code from one part of your program and pasting into another part of your program, you probably should be creating a function instead that is called in both places. Note that duplicated code is more buggy (you would need to update multiple parts of your program if you need to make any updates) and takes more time for someone else to understand.

Empty lines

Include one before any loop, and two before any function definition.

Line length

Make your code so it still looks good in the default putty/terminal size (which is normally 80 characters wide).

Top of the file

At the top of your file include - basic purpose of the file / what it does, the name of the authors, a change-log, if you took anything as a starting point (e.g., code from class or something you found online), if you received assistance from anyone (instructor, unix lab, friend, aunt, etc.), and anything someone would need to keep in mind to run your program properly.