UCC Source Code Documentation Standards

v2: 9/15/2015

Copyright (C) 2015

University of Southern California

Center for Systems and Software Engineering

Table of ContentsPURPOSE AND INTENTION..............................................................3EXECUTION....................................................................................3COMMENT STANDARD....................................................................3NEW FEATURES AND MAJOR MODIFICATION RECORD........................5

DEFECT FIX AND MINOR MODIFICATION RECORD.............................6VERSION HISTORY.........................................................................7

2 UCC Source Code Documentation Standards

Purpose and IntentionUnified 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.

ExecutionFailure to follow the standards and provide sufficient documentation according to this document (or updated versions of this document) will result in possible rejection of integrating the 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 StandardThe 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:

a. 1. Function Description: What is the purpose of the function or segment (what actions does the function or segment perform)?

b. 2. Parameters: Meaning and expected range of values for each parameter.

c. 3. Creation Time and Owner: Creation time of the function or segment and the organization or developer that implemented the function.

UCC Source Code Documentation Standards 3

2. 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.

3. Block comments preceding functions will start with “/*!” in the first line. The number of the sections should be in the same column as the “!”.

4. Each line in the block comment should start with an asterisk (*). 5. Each section title will be on a line by itself, followed by a colon

and space. 6. The first letter of a section’s content should be in the same

column as the first letter of the section title.7. A blank line must separate two sections. 8. 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.

9. 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.

10. 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*/

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

/* Modification: 2015.04

4 UCC Source Code Documentation Standards

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

UCC Source Code Documentation Standards 5

New Features and Major Modification RecordAll 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 Record file. The following information needs to be provided as a single table for each change:

1. Developers and/or Organization2. Date: In MM/DD/YYYY format3. 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

6 UCC Source Code Documentation Standards

Defect Fix and Minor Modification RecordAll 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 Organization2. Date: In MM/DD/YYYY format3. Defect or Modification Description: Summarize the bug/defect, or

the reason behind making the minor code modification4. 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 DateDefect or Modification Description

Description or Copy of Original Code

Description or Copy of New/Modified Code

UCC Source Code Documentation Standards 7

Version HistoryVersion

Date Author(s) Change Description

v1 4/27/15

Dejie Meng, Haowen Fan, Wenchen Tu, 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”

8 UCC Source Code Documentation Standards