Few Notes Regarding Style

int i;main(){for(;i["]<i;++i){--i;}"];read(’-’-’-’,i+++"hell\
o, world!\n",’/’/’/’));}read(j,i,p){write(j/p+p,i---j,i/i);}

— Dishonorable mention, Obfuscated C Code Contest, 1984.
Author requested anonymity.

As the following posts will contain snippets of code, I will introduce few elements of style that may help improve the readability of the text. When the time will come, more about coding will be discussed.

Here is an example of a code fragment:

#define USART1              ((USART_TypeDef *) USART1_BASE)
#define VER_STR              "Version 2.1.3"

void  Com_ISR  (void)                       // USART Rx handler (ISR)
{/////////////////////////////////////////////////////////////////////////////////////////////
    COM_BUFFER *pcom_buf;                   // pointer to COM buffer
    U8          b_char;                     // byte holder
 
    . . . . . .                             // identify the interrupt
    pcom_buf = Com_GetBufPtr (USART1);      // obtain the pointer to the circular buffer
    . . . . . .                             // do other things as required
    b_char = USART_ReceiveData (USART1);    // get one byte from USART1
    Com_WriteRxBuf (pcom_buf, b_char);      // write the byte into the circular buffer
    . . . . . .                             // do other things as required
} ////////////////////////////////////////////////////////////////////////////////////////////

Notes regarding style:

• The syntax coloring scheme shows a bit more than what you see in your everyday editor — here is the key:
  • C reserved keywords
  • Function names
  • Macros
  • Enumerators
  • User data types
  • Preprocessor directives
  • Characters and strings
  • Numbers
  • Comments
  • Operators (+, -, *, etc)

• The code uses portable data types (see the CoOS Real Time Kernel – Part-2).
• Functions that are inside the same module use a common prefix — Com in our case.
• Local functions (visible only in the module) insert a _ (underscore) between the prefix and the rest of the name; to make them local, use the C keyword static (in examples I will omit the static attribute for reasons that will be explained in another post and for simplicity).
• Externalized (or global) functions will concatenate the prefix with the rest of the name.
• Variables that are internal to functions (and not visible anywhere else) will use only lower case letters and underscores; the same convention applies to members of data structures and unions.
• Symbolic constants and macros will use only upper case letters; the same thing applies to user data types.
• Everything else will use capitalized notation (e.g. PrefixName).
• Snippets of code that come from other people’s work will preserve their original style.
• Library functions, constants, macros and type definitions will remain in their original notation.

Try to remember: there are many ways to code programs in C (or any other language). The style adopted is just as good as any other as long as the following goals are attained:

• Portability
• Consistency
• Neatness
• Easy maintenance
• Easy understanding
• Simplicity

This might be enough to get as going…