Rules might not be the best word to have used there, but "Learn the Guidelines Before you Ignore Them" just doesn't have the same ring to it. There are plenty of syntactic rules in the realm of computer programming, software authoring, coding, etc; and there are also plenty of guidelines to be picked up from university study and on the job training. These guidelines are all useful practices I picked up from professors and co-workers, and they're all language-insensitive (except GOTO). With that said, let's begin.

Rule 1: Use Meaningful Variable Names
Convention:

This is generally a good idea. In three months, you're not going to remember what is held in int myCuteInteger;, and if you can't figure out code you wrote, the person inheriting your creation will be no better off. Assuming you're storing the number of employees, int num_employees; is a good name, whereas int temp4; is not. Capitalization versus underscore usage is a non-issue here. There will always be people that say x is better than y, but nobody's going to tell you that cryptic, meaningless variable names are better than meaningful ones. Please note, meaningful does not need to imply extremely long. int number_of_employees_that_work_at_this_company; is no better than int j63tf; in terms of readability and maintainability.

Exception:

i may not be a meaningful variable name to the programmer that began his/her career in 2002, but it is meaningful to quite a few of us. Your instructors use(d) i as a counting variable because they (or someone they knew) used it in FORTRAN, where it was the first available integer (variables that began with a-h were real numbers, and those that began with i-n were integers). It is also okay to count with j, etc., as they follow i. Don't, however, use l, it looks bears an uncanny resemblence to 1.

 

Rule 2: Never Use Global Variables
Convention:

Don't use global variables. They allow unrestricted access to data, which sounds great, but it makes your job harder. When using global variables, there are always two sets of variables to worry about: global and scoped. Also, if you have a global int num_employees;, it's confusing to also have a local int num_employees; (especially in a language like C++ where variables can be declared anywhere in the program).

Exceptions: Global variables are acceptable in a few situations.

  1. Global constant variables are easier and more convenient than hard coding the same number into your program multiple times. After all, you never know when max_array_elements might jump from 50 to 100. C and C++ take care of this with the preprocessor directive, #define, (e.g., #define MAX_ARRAY_ELEMENTS 50) and the const keyword. Those of us that learned C first tend to fall back on #define, but const variables are safer as they are type checked.

  2. When you genuinely need to access a variable from anywhere in the program, it can be more conventient to declare a global than to pass it to every function. Creating a system emulator, where memory constraints are known (and need to be adhered to), registers need to represented, etc. comes to mind.

  3. Status flags are often declared as global variables because it's always nice to know when you're running in non-interactive mode or a file open failed (but the program doesn't need to abort).

 

Rule 3: Avoid GOTO like the plague
Convention:

GOTO is unnecessary in most programs today. It lets you jump anywhere in the program without regard for what memory is allocated, what's in scope, etc. Any time you think GOTO might be convenient, there is guaranteed to be a safer way to do it. GOTO leads to spaghetti code. Also, the GOTO statement is so fiercely hated by some that it is no longer included in some languages (Java, for example, has no GOTO).

Exception:

When optimization is extremely important, GOTO is an appropriate option. It still needs to be used responsibly, and it's not for the faint of heart. For example, GOTO is used in the Linux kernel because it should be fast (as well as stable and a myriad of other things), and by the time you're familiar with the Linux kernel, you can handle a GOTO.

 

Rule 4: Consistently indent your code
Convention:

Choose an indentation style. It doesn't matter which one so long as you like it and your boss/instructor approves. Consistently indented code is immeasurably easier to read than left justified, inconsistently indented, or incorrectly indented code.

Exception:

Large nested if structures can disobey the general guidelines. Which of these looks better to you? Note: The following example makes use of the C-style if-else statement, and it actually makes the code more readable.

void print(int a) {                 |    void print(int a) {
    if(a == 1) {                    |        if(a == 1) {
        printf("a");                |            printf("a");
    } else {                        |        } else if(a == 2) {
        if(a == 2) {                |            printf("b");
            printf("b");            |        } else if(a == 3) {
        } else {                    |            printf("c");
            if(a == 3) {            |        } else if(a == 4) {
                printf("c");        |            printf("d");
            } else {                |        } else {
                if(a == 4) {        |            printf("e");
                    printf("d");    |        }
                } else {            |        return;
                    printf("e");    |    }
                }                   |
            }                       |
        }                           |
    }                               |
    return;                         |
}                                   |

 

Rule 5: Each function should have only one return
Convention:

Each function should have only one return point. This makes tracing the function easier, and it guarantees that every time the function is called, a finite number of paths can be taken, and each path is guaranteed to end at the one exit point.

Exceptions:

  1. File open operations often call for an immediate return. It makes sense to terminate a function when a file can't be opened instead of letting the program crash on the read call or skipping to the return that implies success.

  2. Returning error codes or abnormally terminating a program and displaying an error message on the screen is much easier to handle with multiple return points.

 

Rule 6: Comment Your Code
Convention:

Comment complex and confusing parts of your code. It's as simple as that. Write meaningful comments as you go. If you have a hard time switching from code to documentation and back again, put all of the comments in at the end of a coding session, but don't leave your code and try to comment it 4 days later. Good comments can help you just as much as the person inheriting your code (if not more). Professors/Instructors/Peer Reviewers will understand both what you've done and why you've done it that way if you have commented you code well.

Exception:

I have never come across a situation where a lack of comments could be considered a good thing. Explanations are always good. Comment your code. Please, it might be me that works on it next.

 

Keep in mind, the above rules are really just guidelines. It's completely possible to write coherent programs that use GOTO (You have to in DCL, for one). It's also possible to write all your functions to have exactly two return points in a very readable manner. These rules have served me well, but so have their exceptions.

I realize a lot of my fellow noders are programmers. If you see an error, please /msg me so it can be corrected. Thanks.

Log in or register to write something here or to contact authors.