Suggestions for Writing Computer Programs (By Nelson Padua-Perez)

I. Introduction

The following document provides information on how to write computer programs. We present fundamental/intrinsic tasks you should follow/complete while developing a computer program. The recommendations in this document apply to any programming language you may use.

II. Computer Programming Rules

A. Psychology Behind Computer Programming – As you begin to learn computer programming, you need to keep the following in mind:

1. At first you may feel frustrated as small mistakes (e.g., forgetting a semicolon, initializing a variable) prevent you from moving forward as fast you would like. This frustration is normal and things will get better as you develop your skills; just be patient.

2. It seems that computer programming is second nature for some individuals; if you belong to that group, congratulations. If not, don’t worry about this. You can learn to program and you can become a great programmer; just don’t compare yourself to other people. Remember, in life there will always be people whose skills are better than yours and not as good as yours.

3. Computer Programming Anxiety – When you start working on a programming assignment you may have some anxiety and thoughts similar to “this is impossible,” “there is no way I can finish this,” etc. This anxiety is normal.

B. The Importance of Design

Whether you use pseudocode, UML, and/or any other design tool, the important idea here is that you need to first think about what you need to implement before you start implementing it. Often a person can spent a significant amount of time writing code that does not solve the assigned problem. It is extremely important to first understand the problem you need to solve, otherwise there will be a significant waste of time and effort. For example, if you need to implement a particular algorithm (e.g., a graph algorithm that computes shortest path), make sure you understand the algorithm and have a couple of examples that you have solved yourself before starting to implement any code. These examples will help you in the process of developing your design and verifying that your code is working as expected.

C. Incremental Code Development – This is the most important rule of computer programming! The number one mistake you can make is to try to do too much at once. Incremental code development means adding a little bit of code, checking that the program is generating the expected results, and then moving forward. It is that simple. If you follow this approach you will have an easier time at locating where problems are in your code.

For example, if your program is working, and you add two lines of code and the program stops working, you can bet that the responsible parties are the two lines you just added. Incremental code development is a simple idea that unfortunately escapes people (I guess there is a human gene that gets in the way :)).

Keep in mind that as your programming skills develop what we consider a little bit will vary. For example, beginner programmers can define a little bit as just adding three or four lines of code, but seasoned programmers could write hundreds of lines of code. When in doubt, less is better.

D. Do Not Make Assumptions – Two types of assumptions are common:

1. Assuming the input provided is correct (or has been read correctly) – This will lead to a program that uses garbage to compute values. Always make sure that data has been read correctly otherwise your results will not make sense. Remember GIGO (Garbage In, Garbage Out).

2. Assuming how a language construct works – If you are in doubt regarding what a construct does (e.g., a method, function, operator) stop (!) and look at the appropriate documentation or write a small program that verifies what the construct does.

E. Test All the Time – Testing is a process that can be tedious, but it is extremely important. You should test your system periodically and as often as possible, rather than waiting to the end once coding is completed (or almost complete). Writing tests may prevent you from moving faster, but in the long run it will save you time because:

1. You will identify problems early - If you continue developing code relying on code that has problems eventually these problems are going to surface and finding them will be harder.

2. It gives you confidence in your code - If you test often and thoroughly your code as you develop it, you will have confidence in its correctness; this will simplify the debugging process.

3. You will identify design problems in the system you are implementing early on.

F. Test with Simple Data Sets – Simplify the data sets you use to test your code whenever possible. For example, if you need to implement a sorted list, verify the correctness of the list with the most simple data type (e.g., numbers) you can think of. If the problem originally deals with a list of sorted activities, during testing use a list of integers. It is easier to see what could be wrong by using a simpler data type.

G. Develop an Organized Set of Tests – You need to organize your tests in a way you can convince yourself (and others) you are covering all the possible cases. Before you start writing tests analyze the possible set of cases you can have.

H. Time Management – Unlike writing a paper or other tasks you may be familiar with, computer programming can be very unpredictable in terms of time requirements. The time it can take to finish a computer program can be estimated, but you have to plan and allocate time to deal with unexpected circumstances. If you wait until the last minute to start on a programming task you will not have the opportunity to ask for help or to clarify any doubts.

Keep in mind that computer programming requires significant mental effort; time is needed to rest and being able to focus. Take breaks; don’t keep working on code hour after hour. A 10 minute break can help a lot.

I. Follow a Set of Conventions/Style – As you write code it will help you significantly if you stick with a set of conventions and style (style that you may have defined yourself). For example, rules for naming variables/methods/functions if consistently used can help in the process of writing code. Remembering which variable you need to use is easier if you follow a naming convention.

J. Preventive vs. Corrective programming – There are two approaches you can use while writing code:

Preventive Programming – You are very careful as you write code, considering all possible scenarios, and making sure you test thoroughly as you move along.

Corrective Programming – You are casual about the code you write assuming any problems can be detected later on during the testing/debugging phase.

Preventive programming is the preferred choice. It could feel you are not moving as fast as you wish, but in the long run you will not waste time and effort. Small problems easy to identify in isolation may become extremely hard problems to identify later on once the code is part of a larger system.

K. Understand What You Have Done and Why Things Work – Often you may add a semicolon, use a method/function, etc., and get the expected results without actually understanding why. You need to stop and ask why. Do not move forward without understanding why your system is working. This also applies to scenarios where you are receiving assistance from a colleague, a teaching assistant, etc. Ask them to explain to you any changes they have done that makes your system works now.

L. Learn Language Features by Doing Small Experiments – Nowadays languages offer rich libraries that provide a lot of support. If you are using a library to solve a problem and you are not sure how to use the library, experiment with it in isolation before you use it to solve your problem.

M. Do Not Shy Away From Debugging – Many beginner programmers understand that writing code is about writing the code and then running to someone to find the problems with the code. This is not correct. Writing code means writing the code and finding the problems (debugging) with the code too. After all there is no such thing as the “Company Debugging Person.” There are several reasons for doing your own debugging:

1. Improves your knowledge of the language/libraries – Frequently, problems in your code are the result of a misunderstanding a language construct. Through debugging you will identify these misunderstandings.

2. Programming Skills Improvement – The more debugging you do, the more confidence you will have in writing code. You will be “less afraid” of bugs and your programming skills will increase dramatically.

N. Debugger – A debugger is a great tool, but make sure you understand how to use it before using it. If you are planning to use a debugger, spend some time practicing the debugger with a piece of code that has no errors. This will allow you to practice features of the debugger with code you are familiar with. Your focus will be to understand the debugger.

Keep in mind that if you are careful in the code development process the number of times you will need the debugger is minimal. Also, keep in mind that sometimes a simple output statement could help you in the process of finding problems in your code.

If you are planning to be a professional programmer you need to know how to use the fundamentals tools of a debugger.

O. Be Organized – A computer program is a complex piece of engineering. Organization helps keep this complexity under control. Good variable names, good indentation, appropriate comments all are part of keeping your code well organized.

P. Write Code Like You Will Forget About It Tomorrow – People forget about the code they write. If you look at the code you wrote a couple of months ago you will probably not recognize a large percentage of the code (Of course, after studying the code for a while you will recognize what you did.). As you write code keep in mind you will forget a lot of details and decisions you make. Use appropriate comments and specify any assumptions you have made. It will help others and it will help you.

Q. Keep Backups – You need to have some sort of backup system; something as simple as copies of your files or more sophisticated (e.g., version control provided by CVS). Create backups often and if possible in different computers. Backups allow you to have a copy of your work if you computer fails and they allow you to go back to a previous version of your system.

R. How to Start – Starting a programming assignment can be a daunting task. Make sure you understand the problem you need to solve, and have a design/plan. Don’t be afraid to start even if you don’t have every single detailed thought out; some things you will figure out as you move along in the development process.

S. Be Patient – Programming takes time and effort but it is very rewarding experience. With the passing of time you will become faster at code development. Just be patient.