General Comments

In general: APPLY COMMON SENSE LIBERALLY. If you are unsure as to whether your code is understandable by others, ask others. Never assume. We would all prefer to take 5 minutes and answer your question than have to scratch our heads for 5 hours while we try to debug your code.

Syntax Style Guidelines

1. Use the GNU style guidelines unless explicitly told otherwise. You can find those guidelines at http://www.gnu.org/prep/standards_toc.html.

2. Use four character indents.

3. The open curly brace ('{') should be on the same line as the start of a block, except when declaring functions. e.g.

   
       if (x == y) {
           do_something();
       }
   

4. Do not use single character variable names unless it is an index to a loop. (e.g. for (i=1;i...))

5. Typedef's must end in a _t.

6. #define names must be in all caps. No other variable types may use a variable name with all caps.

7. Never use lines greater than 80 columns. Remember that strings can be broken up into two separate lines like so:

   
       printf ("This is a very very very very very long string, "
               "which cannot fit on one line. But this is okay.");
   
   

8. If you inherit a piece of code that is in another style. Keep the original style. Do not waste your time and energy trying to convert it because more than likely you will break it in the process. If you're not sure about a particular case, ASK.

9. Header files should not contain the complete code to a function.

10. Header files should never allow recursive includes to work. i.e. they should start with lines like #ifndef __MY_HEADER_FILE_H__ and end with #endif /* __MY_HEADER_FILE_H__ */.

11. When you need to take a block of code out, DO NOT COMMENT IT OUT. Instead, use #ifdef/#endif. e.g. #ifdef REMOVE_UNTIL_COFFEE_PROTOCOL_IS_DONE.

12. The question mark operator is to be avoided.

13. All switch statements must have a default clause.

14. Function names should be ANSI style, all in one line with return types on the same line.

15. There must be a comment at the beginning of every function. It should include: the function name what it does, its inputs, and the meaning of its return codes.

16. Comment variable usage.

17. Write correct comments and keep it updated with the code.

Semantic Guidelines

1. Assume all code will need to be understandable by someone else at 4am when you're not around to answer questions.

2. Comment all code liberally. If anyone complains that you comment too much, tell your manager so that person can be transferred to accounting.

3. Feel free to throw README files into the source tree to explain a particular file or design or anything. Be sure the README's are checked in along with the rest of the code.

4. Optimize your writing style for human readability. Do not think you are smarter than the compiler or that you need to "help" the compiler generate more efficient code. This means using plenty of parenthesis and breaking up your code into multiple lines if each line is doing something completely different.

5. NO MAGIC NUMBERS. Never assume that a number will remain constant through the life of the product. Also never assume that someone will understand why the limits are what they are. If you must pick an arbitrary limit (e.g. maximum string size), comment in the code that the number is arbitrary.

6. All string functions must have some method of guaranteeing that they will stop and not crash the system. This means no blind strcpy or sprintf function calls. Instead, use strncpy and snprintf.

7. Minimize scope. If you need to add a global variable stop and ask yourself whether you really need it or not. Understand that you are adding the global namespace pollution by putting it there. Also be sure you can do a complete tree rebuild with your addition.

8. Prototypes should contain names of variables along with their types.

9. Do not code to save space at the expense of performance. Wasting a few bytes to store a simple value (e.g. using an int to store a bool) is much better than bit packing. Bit packing results in many extra instructions generated by the compiler which in most instances is unnecessary. The obvious exception to this rule is those cases where you are constructing a specific structure which requires bit packing. e.g. TCP headers.

10. Always check for error codes. Always be able to handle all error codes.

11. Use typecasting only when necessary. Do not use typecasting for the sole purpose of getting rid of a warning.

12. Any use of goto should be explained.

13. All #if lines should be commented.

14. Use #if (OPTION_A) instead of #ifdef.

Compiling and Makefiles

1. All projects should be compilable by simply typing "make".

2. All Makefiles must be GNU make compliant.

3. All C programs must compile clean with the following flags: -ansi, -pendantic, and -Wall. Any warnings that are generated MUST be explained in the documentation. Exceptions given to standard C header files that generate warnings.

General Comments

1. Remember that the nature of the product requires us to think in terms of both high availability and high throughput. WE MUST NEVER CRASH! We shoust also never have reason to call exit(). All error conditions must be gracefully handled.

2. Fix bugs as they are found. Never say you will get back to a bug later "when you have time," because you will never have time later. (Murphy's Law of Bug Hunting) Furthermore, the magnitude of the bug will only increase as more people build on your check-in.

3. Recommended reading: Writing Solid Code by Steve McConnel.