User Tools

Site Tools


coding_standards

Coding Standards and ECEn 330

Teams that work on programming projects must rely on coding standards to be successful. Often, a company will impose a specific coding standard on all of its programmers. Some companies even go so far as to restrict what data structures you may use (especially with C and C++). Using a coding standard for ECEn 330 labs provides the following benefits:

  1. Your code will be more usable (by you and others later on). Much of the code that you will write for this class will likely be useful in ECEn 390. By following the coding standard outlined here you will more easily be able to reuse your code in various projects.
  2. Your code will be tested. The coding standard requires that you write test code that is included as an essential part of the code that you will write.
  3. Your code will be readable by you and others.

There are two general sections discussed below. The first is a discussion of the general coding standard. The second discusses some coding standards specifics as they pertain to state machines.


The General Coding Standard

General Rules

  • You will write C-code. No class definitions are allowed. If you need a data-structure, it must be something supported by 'C', such as a struct.
  • When compiled, your code will not cause the compiler to issue any warnings or errors. Some of the provided files in “supportFiles” generate warnings, those can be ignored. The files in “supportFiles” were obtained from a variety of places and I didn't modify them to fix the various warnings.
  • Use #define for all scalar constants. You may use the constants 0 and 1 in if-expressions, for-loop expressions and while-loop expressions. You may also use 0 or 1 in arithmetic expressions.
  • Use static const arrays if you need to hard-code test data (or otherwise initialize an array), e.g., static const uint16_t testData[] = {1, 2, 3, 4};, or if you need to declare some series of constant values as an array.
  • Use #define for all string constants EXCEPT when the string contains a printf formatting directive (%d, etc.).
  • Your code, when submitted, must be in a finished form. You are allowed a total of 5 lines of “commented-out” code per file.
  • You must have at least an 50% comment-to-code ratio. If you have 10 lines of code, you must have at least 5 lines of comments. A comment “line” can either be on its own line or start at the end of the source-code line. Either counts as a “line” of comment code.
  • For your own code, avoid the base types such as “int”. Use the types that are contained in <stdint.h>. They are far more descriptive. int main() is OK. See stdint.h
  • You may use the char base type when working with C string functions such as strcpy(), strcat(), etc.
  • Make sure that your code completely describes your intent. If your code is unclear or does not completely describe what is going on, comment accordingly.
  • Avoid using repetitive sections of copied and pasted code in your programs.

Specifics

  • The “.h” file must contain declarations for all constant values, function prototypes, etc., that you want to “advertise” for use.
  • The “.h” file and the “.c” file must have the same base name.
  • “.h” files do not contain executable code, only function declarations, #define, etc.
  • “.h” files must not contain any definitions of any variables whatsoever.
  • “.c” files contain code.
  • All function names and constant values contained in .h files must be prefixed by the base-name of the file + underscore, e.g., buttons_read(), #define BUTTONS_BTN0_MASK 0x1. Function names and constant values that are used only within .c files do not need to be prefixed by the base-name of the file.
  • All scalar constant values must be defined using #define and anything defined by a #define must use all uppercase letters in its name.
  • Use the const key word only if you are defining an array of constant values, e.g., const int foo[2] = {1, 2};
  • The constants 0 and 1 can be used without a #define within if-expressions, and while- and for-loops, e.g., for (int16_t i=0;), if (i==0), and while (1). You can use '1' and '0' to initialize variables. You can also use 0 and 1 in assignment or arithmetic expressions. No other exceptions are allowed. See the code below for examples of how to use '1' and '0'.
  • You don't have to use your #define for strings ONLY if the string contains a printf formatting directive (%d, etc).
  • #define names should be meaningful, e.g., #define TEN 10 may sound clever but you will lose points if you use #define this way.
  • Use proper and consistent indention techniques.
  • Use meaningful comments and add the comments as you develop your code.
  • Busy loops (delays based on for-loops) are OK for test code but are not allowed anywhere else.
  • You will provide an “init” function (base-name_init) that must be called before any of your provided functions can be called. I suggest that you follow the example shown in the code below. The “init” function is required in any case (even if it does nothing).
  • You will provide a “runTest” function (base-name_runTest). This function serves two purposes. First, it tests the code to make sure that it works. Second, you will be able to look at the code later to see how it is used, in other words, the “runTest” code can provide an example of how to use the code.
  • Only code written by you is graded against the coding standard. If you include code from one of the class web-pages and that code violates the coding standard, you will not lose points.

Grading Guidelines (examples of things that cause you to lose points)

  • Bogus #define names, e.g., #define TEN 10
  • Directly using numbers such as 5, 3.14, etc., instead of using a #define (so-called magic numbers).
  • Not using the file-name as the prefix in all function names and #define that show up in the .h file.
  • Not using all upper-case for #define.
  • Each infraction will lose points, e.g., each use of a constant value, e.g., 2, will lose points.
  • Use of types such as int, etc., anywhere in your code. Use integer types from stdint.h instead.
  • Any other infractions of the rules spelled out in General Rules and Specifics above.

Declarations versus Definitions

.h files may contain the following (these are forms of declarations):

  • function prototypes,
  • typedef declaration,
  • #define

.h files may not contain (these are definitions):

  • function definitions,
  • variable definitions.

Examples of function prototypes can be found in the examples of circularBuffer.h shown below. A function prototype “advertises” the name of the function, its return type, and the types of the arguments that it accepts. It does not contain any of the code for the function. A typedef declaration is also shown below. It “declares” types but does not result in any variable definitions. Function definitions are found in circularBuffer.c where the “code” for the entire function can be found for each of the function prototypes in the circularBuffer.h file.

A good but rather detailed discussion of this topic can be found at: declaration versus definition.


coding_standards.txt · Last modified: 2019/06/11 14:18 by hutch