Software engineering

Software engineering

 

Software engineering

 

Coding Standard January 2006 1 2006 by Carnegie Mellon University
Coding Standard January 2006 2 2006 by Carnegie Mellon University
Overview
Overview
Section See Page
Prerequisites 2
Objectives 2
Coding standard requirements 3
Example coding standard 4
Evaluation criteria and suggestions 7
Coding standard template 8
Prerequisites Prerequisites
• Read Chapter 4
• Complete Size Counting Standard
Objectives The objectives of the coding standard are to
• establish a consistent set of coding practices
• provide criteria for judging the quality of the code that you produce
• facilitate size counting by ensuring your programs are written so they can be
readily counted
• for LOC counting, require that there be a separate physical line for each
logical line of code
Coding Standard January 2006 3 2006 by Carnegie Mellon University
Coding standard requirements
Coding
standard
requirements
Produce, document, and submit a completed coding standard that calls for
quality coding practices.
For LOC counting, ensure that a separate physical source line is used for each
logical line of code.
Submit the coding standard with your program 2 assignment package.
Coding Standard January 2006 4 2006 by Carnegie Mellon University
Example coding Standard
Coding standard
example
Pages 5 and 6 of this workbook contain an example C++ coding standard.
Notes about the example
• Since it is an example, tailor it to meet your personal needs.
• If you have an existing organizational standard, consider using it for the PSP
exercises.
Continued on next page
Coding Standard January 2006 5 2006 by Carnegie Mellon University
Example C++ Coding Standard
Purpose To guide implementation of C++ programs
Program Headers Begin all programs with a descriptive header.
Header Format /******************************************************************/
/* Program Assignment: the program number */
/* Name: your name */
/* Date: the date you started developing the program */
/* Description: a short description of the program and what it does */
/******************************************************************/
Listing Contents Provide a summary of the listing contents
Contents
Example
/******************************************************************/
/* Listing Contents: */
/* Reuse instructions */
/* Modification instructions */
/* Compilation instructions */
/* Includes */
/* Class declarations:
*/
/* CData
*/
/* ASet
*/
/* Source code in c:/classes/CData.cpp: */
/* CData
*/
/* CData()
*/
/* Empty()
*/
/******************************************************************/
(continued)
Coding Standard January 2006 6 2006 by Carnegie Mellon University
Example C++ Coding Standard (continued)
Reuse
Instructions
– Describe how the program is used: declaration format, parameter values, types,
and formats.
– Provide warnings of illegal values, overflow conditions, or other conditions that
could potentially result in improper operation.
Reuse Instruction
Example
/******************************************************************/
/* Reuse instructions */
/* int PrintLine(char *line_of_character) */
/* Purpose: to print string, ‘line_of_character’, on one print line */
/* Limitations: the line length must not exceed LINE_LENGTH */
/* Return 0 if printer not ready to print, else 1 */
/******************************************************************/
Identifiers Use descriptive names for all variable, function names, constants, and other
identifiers. Avoid abbreviations or single-letter variables.
Identifier
Example
Int number_of_students; /* This is GOOD */
Float: x4, j, ftave; /* This is BAD */
Comments – Document the code so the reader can understand its operation.
– Comments should explain both the purpose and behavior of the code.
– Comment variable declarations to indicate their purpose.
Good Comment If(record_count > limit) /* have all records been processed? */
Bad Comment If(record_count > limit) /* check if record count exceeds limit */
Major Sections Precede major program sections by a block comment that describes the processing
done in the next section.
Example /******************************************************************/
/* The program section examines the contents of the array ‘grades’ and calcu- */
/* lates the average class grade.
*/
/******************************************************************/
Blank Spaces – Write programs with sufficient spacing so they do not appear crowded.
– Separate every program construct with at least one space.
Indenting – Indent each brace level from the preceding level.
– Open and close braces should be on lines by themselves and aligned.
Indenting
Example
while (miss_distance > threshold)
{
success_code = move_robot (target _location);
if (success_code == MOVE_FAILED)
{
printf(“The robot move has failed.n”);
}
}
Capitalization – Capitalize all defines.
– Lowercase all other identifiers and reserved words.
– To make them readable, user messages may use mixed case.
Capitalization
Examples
#define DEFAULT-NUMBER-OF-STUDENTS 15
int class-size = DEFAULT-NUMBER-OF-STUDENTS;
Coding Standard January 2006 7 2006 by Carnegie Mellon University
Evaluation c riteria and suggestions
Evaluation
criteria
Your standard must be
• complete
• legible
Suggestions Keep your standards simple and short.
Do not hesitate to copy or build on the PSP materials.
Coding Standard January 2006 8 2006 by Carnegie Mellon University
Coding Standard Template
Purpose To guide the development of programs
Program Headers Begin all programs with a descriptive header.
Header Format
Listing Contents Provide a summary of the listing contents.
Contents
Example
Reuse Instructions • Describe how the program is used. Provide the declaration format, parameter
values and types, and parameter limits.
• Provide warnings of illegal values, overflow conditions, or other conditions that
could potentially result in improper operation.
Reuse Example
Identifiers Use descriptive names for all variables, function names, constants, and other
identifiers. Avoid abbreviations or single letter variables.
Identifier Example
(continued)
Coding Standard January 2006 9 2006 by Carnegie Mellon University
Coding Standard Template (continued)
Comments • Document the code so that the reader can understand its operation.
• Comments should explain both the purpose and behavior of the code.
• Comment variable declarations to indicate their purpose.
Good Comment
Bad Comment
Major Sections Precede major program sections by a block comment that describes the
processing that is done in the next section
Example
Blank Spaces • Write programs with sufficient spacing so they do not appear crowded.
• Separate every program construct with at least one space.
Indenting • Indent every level of brace from the previous one.
• Open and closing braces should be on lines by themselves and aligned with
each other.
Indenting
Example
Capitalization • Capitalized all defines.
• Lowercase all other identifiers and reserved words.
• Messages being output to the user can be mixed-case so as to make a clean
user presentation.
Capitalization
Example

 

Size Counting Standard January 2006 1  2006 by Carnegie Mellon University
Section See Page
Prerequisites 2
Objectives 2
Size counting standard requirements 3
Example 1: Pascal size counting standard 4
Example 2: C++ size counting standard 6
Example 3: another size counting standard 8
Evaluation criteria and suggestions 10
Size counting standard template 11
Prerequisites Prerequisite reading
• Chapter 3
Objectives The objectives of Size Counting standard are to
• define the size counting standards that are appropriate for the programming
language and environment that you will use
• provide a basis for developing a coding standard
• prepare for developing a program to count program size
Size Counting Standard January 2006 2  2006 by Carnegie Mellon University
Size counting standard requirements
Size counting
standard
requirements
Produce and document a standard for counting program size for the language
and environment that you will use in this course.
Submit the completed standard using the format in the template on page 11
with your program 2 assignment package.
Size Counting Standard January 2006 3  2006 by Carnegie Mellon University
Example 1: Pascal size counting standard
Overview The template is a simplified version of the SEI measurement framework.
• Use this template to describe important items.
• Tailor it to fit your needs or language.
We’ll walk through two example size counting standards. The first example is
for logical LOC for Pascal programs.
Completing the
header
Complete the header as follows:
• the name you give this standard
• the language you are using
• your name
• the date you produced this standard (or revision)
Count type Choices are logical and physical LOC.
• Logical LOC counts language elements.
• Physical LOC counts text lines.
For this counting standard, you are counting logical LOC.
Statement type Use this section to define how you will count various types of statements.
Consider the following:
• How are you going to count procedure declarations and function prototypes?
• How will you count compiler directives?
• Will you count blank lines or comments? Why or why not?
Clarifications A fully operational standard generally requires many notes and comments.
Use the clarification section for this purpose.
Continued on next page
Size Counting Standard January 2006 4  2006 by Carnegie Mellon University
Pascal LOC Counting Standard Template
Definition Name: Example Pascal LOC Std. Language: Pascal
Author: W. S. Humphrey Date: 12/20/93
Count Type Type Comments
Physical/Logical Logical
Statement Type Included Comments
Executable yes
Nonexecutable:
Declarations yes
Compiler Directives yes
Comments no
Blank lines no
Other elements
Clarifications Examples/Cases
Nulls yes continues, no-ops, …
Empty statements yes “;;”, lone ;’s, etc.
Generic instantiators
Begin…end note 1 when executable
Begin…end note 1 when not executable
Test conditions yes
Expression evaluation yes when used as sub program arguments
End symbols notes 1,2 when terminating executable statements
End symbols notes 1,2 when terminating declarations or bodies
Then, else, otherwise note 1
Elseif note 1
Keywords notes 1,2 procedure division, interface, implementation
Labels yes branch destinations when on separate lines
Note 1 unless followed by ; or. or included in {}, count the
following keywords once: BEGIN, CASE, DO, ELSE, END,
IF, RECORD, REPEAT, THEN, UNTIL
Note 2 count every ; and . that is not within a {} or ()
Note 3 count each , between USES and the next ; or between
VAR and the next ;
Size Counting Standard January 2006 5  2006 by Carnegie Mellon University
Example 2: C++ LOC counting standard
How many
LOC?
Using the C++ LOC counting standard on page 7, how many LOC are in the
following program fragment?
#include <stdio.h>
void main (void)
{
int i,j;
for (i = 0; i < 10; i++)
for (j = 0; j < 10; j++)
cout << i << “, ” << j << endl;
}
Continued on next page
Size Counting Standard January 2006 6  2006 by Carnegie Mellon University
Example C++ Size Counting Standard
Definition Name: Example C++ LOC std. Language: C++
Author: W.S. Humphrey Date: 12/20/93
Count Type Type Comments
Physical/Logical Logical
Statement Type Included Comments
Executable Yes
Nonexecutable:
Declarations Yes,Notes
3, 4
Compiler Directives Yes, Note 4
Comments No
Blank lines No
Other elements

Clarifications Examples/Cases
Empty statements yes “;;”, lone ;’s, etc.
Begin…end note 1
Expression evaluation yes when used as sub program arguments
End symbols notes 1,2 for terminating executable statements, declarations,
bodies
Then, else, otherwise note 1
Elseif yes
Keywords yes procedure division, interface, implementation
Labels yes branch destinations when on separate lines
Note 1 Count once every occurrence of the following key words:
CASE, DO, ELSE, ENUM, FOR, IF, PRIVATE, PUBLIC,
STRUCT, SWITCH, UNION, WHILE
Note 2 count once every occurrence of the following: ; , {} or };
Note 3 count each variable or parameter declaration
Note 4 count once each #define, #ifdef, #include, etc.
statement
Size Counting Standard January 2006 7  2006 by Carnegie Mellon University
Example 3: another size counting standard
Overview For this example standard, the class will select from among the following
product categories.
• documents
• interface screens and forms
• database program elements
• maintenance fixes
• any other requested category
We’ll then walk through developing the selected size counting standard.
Completing the
standard
We’ll then walk through the completion of the standard as a class exercise.
Continued on next page
Size Counting Standard January 2006 8  2006 by Carnegie Mellon University
Size Counting Standard Template
Definition Name: Language:
Author: Date:
Count Type Type Comments
Physical/Logical
Statement Type Included Comments
Executable
Nonexecutable:
Declarations
Compiler Directives
Comments
Blank lines
Other elements

Clarifications Examples/Cases
Note
Note
Note
Note
Size Counting Standard January 2006 9  2006 by Carnegie Mellon University
Evaluation criteria and suggestions
Evaluation
criteria
Your standard must be
• complete
• legible
Suggestions Keep your standards simple and short.
Do not hesitate to copy or build on the PSP materials.
Size Counting Standard January 2006 10  2006 by Carnegie Mellon University
Size Counting Standard Template
Definition Name: Language:
Author: Date:
Count Type Type Comments
Physical/Logical
Statement Type Included Comments
Executable
Nonexecutable:
Declarations
Compiler Directives
Comments
Blank lines
Other elements

Clarifications Examples/Cases
Note
Note
Note
Note