19. File Sections
File Section Headings start at current indent level and end after column 75:
Major:
column 75
|
v
/**************************************************************************
* Example Heading -- ALWAYS has at least 3 blank lines above it.
* It isn't imperative that comment text be restricted to column 75, but it looks
* nicer when it does. The above line is an example which looks better when
* wrapped before it extends beyond the space of the "block". Sometimes this
* is not practical though.
***************************************************************************/
^
|
column 75
Middle — used only when an additional heading “level” is needed:
/*=========================================================================
* Example Heading -- ALWAYS has at least 2 blank lines above it.
*=========================================================================*/
Minor — common:
/*-------------------------------------------------------------------------
* Example Heading -- ALWAYS has at least 1 blank line above it.
*-------------------------------------------------------------------------*/
/* Common among lines of code. This comment labels the code below it... */
<some source code here>
/* Whereas this indented comment labels the code above it. */
/*------------------------- 28-Nov-2012 11:56 vw --------------------------
* Timestamped Comment -- used for longer text that should stand out when
* the modification time is pertinent, e.g. when long-standing source code
* is undergoing a modification.
*-------------------------------------------------------------------------*/
/* 28-Nov-2012 11:56 vw
* This is the format of a minor change were original source code should
* be preserved. This is used frequently in "delicate" source code and
* is very useful when a team is working together on source code.
*
* Original code:
BTN_WaitForUserToReleaseLeftButton();
++luiCurrMenuItem;
*/
BTN_WaitForUserToReleaseRightButton();
luiCurrMenuItem += 2;
//{ 28-Nov-2012 12:02 vw
// If needed, a modification can look like this also.
// Original code:
// <commented out source code here>
<new source code here>
//}
Re the above, keep in mind, this is used rarely since we try to stick with ANSI-standard C code, and EOL comments aren’t allowed in ANSI C. :-(
Alternately, when compliance with ANSI C rules is important:
/*{ 28-Nov-2012 12:02 vw
* If needed, a modification can look like this also.
* Original code:
<commented out source code here>
*/
<new source code here>
/*}*/