It is strongly recommended that you submit a draft a few days before it is due and request quick feedback. There is no need to submit a draft to your customer(s) or user(s), unless they have particularly strong computer science expertise to assist in code evaluation, in which case they should be invited to attend (but are of course not required to attend) code inspection meetings.
 

Purpose of This Assignment

• To achieve group consensus on developing or adopting practical coding and commenting conventions.
• To learn how to perform code inspections among "egoless" team members.
• To appreciate how error correction costs can be significantly reduced by discovery early during the coding phase, rather than later during the testing phase or after installation.

Required Activities

• Define project-specific commenting and coding conventions (or adopt/modify other popular conventions).
• Compile and build all code without fatal errors and with only minimal warnings (and analogously for parse/display wrt scripts, marked up documents, etc.).
• Inspect together, as a team, all significant pieces of code written to date, including scripts and markup. Code inspection meetings may be virtual rather than physical, although this may be more difficult. You will need to take copious notes during inspection meetings in order to fulfill the content requirements of the Code Inspection Report. Understand what information you will need to record before each meeting.
• Include in the CIR the actual text of the code that was inspected in both its "before" and "after" forms (i.e., before and after detected defects have been repaired). You do not need to submit all code, just the inspected code referenced in the CIR (which should be most of your code). Place the code in Appendix B.

Outline

Title Page

• Document title
• Version #
• Client name
• Customer name
• Team members names
• Date

Table of Contents

• Document title
• List all sections with page numbers

1.0 Introduction

1.1 Coding Conventions

Summarize your commenting and coding conventions.

• Explain the rationale underlying their development (if original to your team) and/or adoption (if adopted from elsewhere).
• Elaborate the conventions fully in Appendix A with guiding examples. If you adopted any conventions, they should also be listed in the appendix with the source cited. If you adopted any conventions, but adjusted them, explain the adjustments.

1.2 Defect Checklist

Show the tabular checklist of possible defects that you used during the inspection process. Remember to take into consideration defects that are programming language-specific.

1.3 Code Inspection Process

Briefly describe the code inspection process your team followed. Give the process really followed, not the "ideal" process. If your process was relatively far from the ideal, explain why you chose to so diverge as well as how.

• Credit will not be taken off for following a non-standard process if that process seems likely to have led to your reported results.
• Credit will be taken off for describing a process that does not seem to match your reported results.

1.4 Impressions of the Process

Sketch your general impressions of the code inspection process and of the quality of your program, both prior to the code inspection and after any repairs actually made.

• Indicate which are the "best" one or two modular units in your program (in terms of relatively small likelihood of remaining flaws), and why you think so.
• Indicate which are the "worst" one or two modular units in your program (in terms of relatively large likelihood of remaining flaws), and why you think so.

1.5 Inspection Meetings

Give references for all actual meetings, whether physical or virtual, and for any other non-obvious documents and/or external tools referenced or used during code inspection or otherwise in the preparation of this document.

• For each code inspection meeting, specify date, location (virtual as well as physical), time started, time ended, who attended, who performed which roles, and which particular files or other code units were covered in that meeting.

2.0 The Code Inspection

Minor utility modules may be omitted, but make sure to list any that were. Present the following for every source code module that was inspected.

• Briefly describe where this module fits into the design and architecture. Normally it should implement a modular unit that comprises all or part of a major domain component, design component, or object (from the SDD).
  • If it did not appear in the SDD, explain why it was added (and revise the SDD).

• Discuss quality and quantity of comments and adherence to coding conventions (or lack thereof).

• If there are any differences between the modular unit's design (from the SDD) and the actual code, then
• Compare the planned module interface to the actual interface implemented.
• Compare the planned data structures to the actual data structures implemented.
• Compare the planned user and file I/O to the actual I/O implemented.
• Compare the planned algorithms to the actual algorithms implemented.
• Consider, with respect to all of the above, tradeoffs (e.g., worst case time vs. space, ease of implementation and testing, and opportunities for design/code reuse).

3.0 Defects

Reports indicating zero or very few defects are unlikely to be believable. Think of this as a "treasure hunt" and find as many defects as possible. But please do not insert defects intentionally.

Present the following for each defect found, including coding convention-noncompliance.

• Name of the module in which the defect was found.

• Describe the defect, making clear in what way it is deficient, and categorize it as one of the following:
  • Correctness with respect to the functional specification (does it look like it does what is required?).
  • Completeness with respect to that specification (is it missing? does it completely fulfill the requirement or only partially?).
  • User friendliness (here is where to consider handling of user input errors as well as prompts and all other information displayed to the user).
  • Testability (the specification and user interface may not be directly relevant to all modules, but testability at the "unit test" level should always be considered).
  • Other (e.g., minimizing inter-module coupling, maximizing intra-module cohesion).

• Indicate whether or not the defect has been fixed.
• If it was fixed, briefly describe the debugging process, if any, outside of the code inspection itself.
• If it is not yet fixed, but you intend to fix it later (that is, before system transition) indicate so.
• If you do not plan to fix it prior to system transition, briefly explain why it is deemed too difficult or not suffiiciently beneficial to repair (within reasonable severity/cost-to-repair constraints).

Appendix A. Coding Conventions

Elaboration of the coding conventions discussed in Section 1.0.

Appendix B. Code

Listings of all code that underwent the code inspection process. Include both the "before" and "after" versions of the code.