From 4ef8209fed8067855d9ed7b56db3799d57c3253f Mon Sep 17 00:00:00 2001 From: skarg Date: Tue, 30 Nov 2010 06:32:42 +0000 Subject: [PATCH] Added some text to the coding standard about variable names. --- bacnet-stack/doc/code-standard.txt | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/bacnet-stack/doc/code-standard.txt b/bacnet-stack/doc/code-standard.txt index a12f787a..12548865 100644 --- a/bacnet-stack/doc/code-standard.txt +++ b/bacnet-stack/doc/code-standard.txt @@ -2,13 +2,26 @@ This software runs on many platforms, and can be compiled with a number of different compilers; here are some rules for writing code that will work on multiple platforms. -Regarding tabs, indenting, and code style, we run: +Regarding tabs, indenting, and code style, we run: $ indent -kr -nut -nlp -ip4 -cli4 -bfda -nbc -nbbo -c0 -cd0 -cp0 -di0 -l79 filename.c on the code prior to releasing it. This ensures a standard look and feel to the code regardless of the authors preferred style. You may certainly adjust the code to your preferred style using an indent tool. We use the script indent.sh to adjust all the .c and .h files. +For variable names, separate words within the variables by underscores. +Do not use capital letters as separators. Consider how much harder +IcantReadThis is on the eyes versus I_can_read_this. + +Variable and function names are defined with the first words being +descriptive of broad ideas, and later words narrowing down to specifics. +For instance: Universe_Galaxy_System_Planet. Consider the following names: +Timer_0_Data, Timer_0_Overflow, and Timer_0_Capture. This convention +quickly narrows variables to particular segments of the program. +Never assume that a verb must be first, as often seen when naming functions. +Open_Serial_Port and Close_Serial_Port do a much poorer job of grouping +than the better alternative of Serial_Port_Open and Serial_Port_Close. + Don't use C++-style comments (comments beginning with "//" and running to the end of the line) for modules that are written in C. The module may run through C rather than C++ compilers, and not all C compilers @@ -69,7 +82,7 @@ something such as done: } - + will not work with all compilers - you have to do if (...) { @@ -123,7 +136,7 @@ integral data types larger than 1 byte, and floating-point data types, cause a trap, which will, at best, result in the OS slowly performing an unaligned access for you, and will, on at least some platforms, cause the program to be terminated. - + The data in a packet is not necessarily in the byte order of the machine on which this software is running. Make use of big_endian() which returns non-zero on big_endian machines. @@ -149,7 +162,7 @@ carriage return/line feed). In addition, that also means that when opening or creating a binary file, you must use "open()" (with O_CREAT and possibly O_TRUNC if the -file is to be created if it doesn't exist), and OR in the O_BINARY flag. +file is to be created if it doesn't exist), and OR in the O_BINARY flag. That flag is not present on most, if not all, UNIX systems, so you must also do @@ -216,7 +229,7 @@ Try to write code portably whenever possible, however; note that there are some routines in the software that are platform-dependent implementations. The platform independent API is declared in the header file, and the dependent routine is placed in a ports directory. - + Reference: The cross platform aspect of this coding standard is based -on the developer coding standard for Ethereal/Wireshark and has been +on the developer coding standard for Ethereal/Wireshark and has been modified by Steve Karg for this project. Thank you, Ethereal/Wireshark!