UCC Source Code Documentation Standards /
v2: 9/15/2015 /

Copyright (C) 2015

University of Southern California

Center for Systems and Software Engineering

Table of Contents

Purpose and Intention

Execution

Comment Standard

New Features and Major Modification Record

Defect Fix and Minor Modification Record

Version History

Purpose and Intention

Unified Code Count (UCC) is an open source project hosted by University of Southern California Center of Systems and Software Engineering (USC CSSE). Most of the development effort is done at USC with high turnover. Additionally, many users contribute very useful code modifications. All of these sources of code modifications make USC CSSE’s task of integrating the code contributions and producing high quality releases. In order to reach this goal, USC CSSE has constructed standards of how to document code modifications. Please review the different types of comments and documents required with code modifications.

Execution

Failure to follow the standardsand provide sufficient documentation according to this document (or updated versions of this document) will result in possible rejection of integratingthe contributions into the official UCC baseline, developed and maintained by USC CSSE. Though the Comment Standard must be followed, sufficient communication may substitute the code modification records described below.

This is effective as of September 15, 2015.

Comment Standard

The following comment standard applies to new functions, code modifications, and medium to large code segments performing a particular task.

  1. For each function, there should be a comment block above the function with the following sections:
  2. 1. Function Description: What is the purpose of the function or segment (what actions does the function or segment perform)?
  3. 2. Parameters: Meaning and expected range of values for each parameter.
  4. 3. Creation Time and Owner: Creation time of the function or segment and the organization or developer that implemented the function.
  5. Within each function, if the code is modified after the creation date, the line of code should be preceded by a comment beginning with the word “Modification”, followed by a colon and a blank space, and then followed by the time in the “YYYY.MM” format. An additional comment line justifying the modification being made should follow this line.
  6. Block comments preceding functions will start with “/*!” in the first line. The number of the sections should be in the same column as the “!”.
  7. Each line in the block comment should start with an asterisk (*).
  8. Each section title will be on a line by itself, followed by a colon and space.
  9. The first letter of a section’s content should be in the same column as the first letter of the section title.
  10. A blank line must separate two sections.
  11. For section 2: Parameters, list each of the parameters on a separate line followed by a colon and blank space, and a brief description of the parameter.
  12. For section 3. Creation Time and Owner, the contents may be on the same line as the section title. The date format is “YYYY.MM”. The date should be followed by a semi-colon and space, and the developer’s and/or organization’s name making the code contribution.
  13. The following is a good example of a block comment preceding a function:

/*!

* 1. Function Description:

* Returns a string without leading/trailing spaces or tabs

* Returns trimmed string

*

* 2. Parameters:

* str: original string

* s: string that has been trimmed

*

* 3. Creation Time and Owner: 2009.01; USC

*/

  1. The following is a good example of a comment preceding code modifications within a function:

/* Modification: 2015.04

* Fixed for-loop constraints to prevent infinite looping */

New Features and Major Modification Record

All implementation of new features, creation of new files and functions, major modification of existing files and functions, and deletion of existing files and functions need to be recorded in the New Features and Major Modification Recordfile. The following information needs to be provided as a single table for each change:

  1. Developers and/or Organization
  2. Date: In MM/DD/YYYY format
  3. Description of New Feature or Code Modification: Summarize the functionality of the new feature or goal of the code modifications.
  4. New/Modified/Deleted File(s)/Function(s): List the files and functions that were created, modified, or deleted (one per row – add rows for additional files/functions)
  5. Description: To the right of each file/function, give a brief description of the new file/function, the modifications done to the file/function, or why the file/function was deleted

The following is a blank template of the table describing a new feature or code modifications to support a goal.

Developers/Organization / Date
Description of New Feature or Code Modification
New Files / Description / New Functions / Description
Modified Files / Description / Modified Functions / Description
Deleted Files / Description / Deleted Functions / Description

Defect Fix and Minor Modification Record

All defect fixes and minor modifications to existing code (such as a change in a few lines of code) need to be recorded in the Defect Fix and Minor Modification Record file. The following information needs to be provided for as a single table for each fix and change:

  1. Developers and/or Organization
  2. Date: In MM/DD/YYYY format
  3. Defect or Modification Description: Summarize the bug/defect, or the reason behind making the minor code modification
  4. Description or Copy of Original Code: Be detailed in the description, and include the file and function names of the original code
  5. Description or Copy of New/Modified Code: Explain the fix or modification in detail, and include the file and function of new/modified code

The following is a blank template of the table describing a defect fix or minor modification to support a goal.

Developers/Organization / Date
Defect or Modification Description
Description or Copy of Original Code
Description or Copy of New/Modified Code

Version History

Version / Date / Author(s) / Change Description
v1 / 4/27/15 / DejieMeng, Haowen Fan, WenchenTu, Jiliang Li, Rajesh Reddy Malireddy, Yunpeng Chen / Initial development of the Standards
v2 / 9/8/15 / Anandi Hira / Format and organization changes. Added sections “Purpose and Intent” and “Execution”
UCC Source Code Documentation Standards / 1