Program Commenting CS-212 Dick Steflik

Commentary Commentary are pieces of information included in a program’s source files to provide additional information about; –what the program does textual description of –how it does it information about non-trivial aspects of the program –inputs & outputs data required for operation and information produced –who wrote it author & maintenance –release information –copyright information who owns the IP (Intellectual Property)

Comment Characters multi-line comments –must be included between /* and */ –used mostly for information blocks such as header blocks for programs and functions single line comments –preceded with // characters –used in-line usually preceding a program control statement end-of-line comments – precede with // –used mostly for data definition, explaining variable use (program and state)

Target Audience maintenance programmers –maintain a program throughout its lifecycle, leave a paper trail of everyone that has worked on a program and what they did software engineers –to design programs and interfaces to programs auditors –not programmers, have programs to strip away code and leave the comments, used to insure specification compliance application programmers –to figure out how to use reuseable packages (ex. math.h)

Header Comments in.c files comments at the beginning of the program or function address things needed by a maintenance programmer –explanation of non-trivial algorithms –side-effects – global data that the program or function might modify without going through the program or function arguments –date and author of both original code and modifications. –version information –copyright notice –explanation of inputs and outputs –data limitations

Header Comments in.h files The header file can be thought of as a user’s manual for the package comments should address how to use information (not how it works) should state any limitations of the code –range limits –exceptions doesn’t usually need to identify author should have version information copyright information (IP)

Variable Comments All variables should have an end-of-line comment saying what the variable is used for –this includes individual fields of a struct –#defines should be commented and collected together at the beginning of the code unit (file)

In-line comments these are whole line comments usually places on the line preceding program control statements (if, while, for, switch, function invocations…) the idea is that all statements that alter to top to bottom execution of a program increase the program complexity and deserve an explanation what is going to happen

Pre and Post Conditions an approach to commenting data structures where the variables defined to represent a data structure represent its state each function, in its header block states the state before a function invocation (precondition) and the expected state modification caused by the invocation (postcondition)

stack, push example /**********************************************************************************************/ /* Name: void push(stack * id, int value) */ /* inputs : id – variable name of the stack ; value – integer to be added to stack */ /* outputs : none */ /* precondition – the stack is empty */ /* postcondition – the stack is non empty and contains one additional item at its top */ /**********************************************************************************************/