7.4.0.10

Reviews

at least we
don't have to obfuscate it before we ship it

The goal of a design review/code walk is to obtain an overview of a specification or code base and to discover its problematic parts.

As a presenter, proceed as follows:
  • Introduce yourself.

  • Remind the readers of the task for which you present a design/code repo.

  • Start with an overview; the README is often helpful here.

  • Run the unit tests.

  • Present the components and their functionality in a top-down fashion, that is, start with the important one and navigate to those that you think are complicated and possibly broken.

  • Refine as the panel requests.

For an evaluation of presentations, we will consider the following aspects:
  1. the presentation suggestions from above;

  2. the desire to work with the panel on the most difficult parts of the project. For example, a presenter should never ask "what do you want to see next".

  3. the presenter’s ability to work with the panel in an interactive manner. In particular, a presenter should never discuss problems abstractly but always direct the attention of the panel to concrete pieces of design documents, comments, or lines of code.

  4. the presenter must know when to acknowledge a potential problem in the code and, equally important, must realize when it is time to reject criticism with concrete justifications (point to a test, highlight a part of your specification).

  5. each presenter is in obvious command of all the code, because the code is created in pair-programming sessions.

The grades for presenters are chosen from OK+, OK, OK-, and ZERO.

As a reader, you will play three different roles:
  • head reader; as such you are responsible to keep the presentation on track;

  • assistant reader; you and the head reader find mistakes, omissions, and questionable design decisions;

  • secretary; you keep track of the questions that the readers ask, note discoveries of problems, take notes, and summarize the to-do items as a memo.

When we evaluate the quality of the readers, we are focusing on these points:
  1. OK+ means the reader discovers solid problems and articulates them well. This appears to depend on the quality of the code bases. Because all code bases are somewhat flawed, however, the quality of the presented code doesn’t really affect your ability to get this grade.

  2. OK means the reader asks pertinent questions and discovers some problems.

  3. OK- means the reader asks questions and some of them are pertinent.

  4. ZERO means the reader didn’t ask any questions or asked too few questions pertinent to the code/design at hand.

A secretary who asks pertinent questions receives bonus points.

When you are secretary you are responsible to get a copy of the written notes to the TA of your section within 24 hours. Once the report is acceptable, we will forward it to the reviewed pair; until then, we will request edits.

The HTML memo from the secretary to the presenters must include the following information:
  1. the presenters

  2. the panelists

  3. the title of the project presented

  4. the date and time

  5. an enumeration (ordered list) of problems discovered. Describes those problems in enough details so that the presenters can reconstruct it and fix it from the information specified.

  6. If the panel discussed potential solutions with the presenters, include these suggestions with the appropriate bullet.

Recall that panels do not usually discuss solutions, however, with the presenters.

The evaluation of a memo will take into account the timely delivery of the first draft, its format, its information content, and basic English writing (typos, grammar mistakes). The latter will affect your grade in a serious manner if the mistake allows a misinterpretation of a sentence or if the mistake makes an interpretation extremely difficult.