Skip to content

Review Another Team’s Code-Level Docs

Treat this like a professional peer review: your job is to help the other team make their code-level documentation (inline comments, code blocks, docstrings) clearer, more truthful, and more useful for real readers (maintainers, users of the API, and future you). The deliverable is a GitLab issue in their repo with your structured feedback.

No Superficial Reviews or BS

Generic, copy-pasted, or buzzwordy feedback is unacceptable. Whether you write it yourself or use an assistant, your review must reference concrete lines, symbols, and behaviors from the actual codebase (file paths, function names, parameters, snippets). If your comments wouldn’t help the target team take a specific action, rewrite them.

Goal

Practice evaluating code-level documentation for correctness, clarity, and audience fit, and give actionable suggestions grounded in the code you read and run.

Scope

Focus only on:

  • Inline code comments (within functions/classes and near tricky logic).
  • Docstrings (module/class/function docs).
  • Code blocks in documentation (README/wiki/how-to pages that show commands/usages).

What to Do

  1. Get oriented & run things Build/run the project or the relevant module. Note actual behaviors, errors, and edge cases—these anchor your review in facts.
  2. Trace code to docs Pick representative modules (public API + at least one non-trivial internal module). Map functions/classes ↔ docstrings, tricky logic ↔ inline comments, and README code blocks ↔ real commands.
  3. Open a GitLab issue titled Review: Code-level Docs – from Team [Your Team Name] Assign your tutor; write your review in sections (see below).

What to Cover (use clear headings)

1) Inline Comments — “Explain the Why”

  • Do comments explain why the code is this way (invariants, algorithm choice, non-obvious constraints), not just restate the what that the code already shows?
  • Are comments placed at the decision points (branching, error handling, performance trade-offs)?
  • Remove/update any comments that are stale, contradict the code, or paraphrase variable names. Provide file:line references and suggested replacements.

2) Docstrings — “Document the Contract”

  • Do public functions/classes have docstrings that state: purpose, parameters (types/units/ranges), returns, raises, and side effects?
  • Are examples runnable and minimal? If they fail when you try them, paste a corrected example.
  • Flag missing edge cases and ambiguous terms (“fast,” “large,” “valid”) and propose exact wording.

3) Code Blocks in Docs — “Copy-Paste Truth”

  • Can a user copy-paste commands/snippets from README/wiki and get the described result? If not, fix paths, flags, and pre-reqs.
  • For multi-step examples, add the expected output or a brief checksum so users know success when they see it.
  • Suggest structure: use fenced blocks with language hints, annotate lines sparingly, and keep one idea per block.

Evidence Rules (how to be specific)

  • Reference files and lines (e.g., api/report.py:115–134) and include short quoted snippets (3–6 lines) when needed.
  • When you suggest a rewrite, show before/after for a single function/docstring.
  • If you claim something is wrong, attach the command/output that proves it.

Deliverable Structure (copy this outline)

  • Summary (3–5 bullets): biggest wins + biggest risks.
  • Inline Comments: 3–6 targeted findings with file:lines and fixes.
  • Docstrings: coverage %, 3–6 targeted rewrites, missing sections.
  • Code Blocks: pass/fail table for each snippet you tried + fixes.
  • Highlights & Next Steps: 2 strengths, 2–3 actionable priorities.

Example Snippets (style illustration)

Inline Comment etl/parse.py:78–90 uses a sentinel None to mean “auto-detect,” but the comment says “skip.” Replace with: “None ⇒ auto-detect encoding via chardet; empty string ⇒ skip detection and use default.” Also assert non-empty when --no-detect is set.

Docstring report.generate(summary: pd.DataFrame, *, fmt: Literal["csv","json"]) -> str Add sections: Args, Returns (path string), Raises (ValueError for empty frame), Examples (minimal). Your CLI example currently writes to CWD but the docstring claims a temp dir—make them match.

Code Block README’s “Quick start” uses python -m app run --config config.yml; the actual module is app.cli. Update block and add the expected “Server started on :8000” line so users can verify success.

Timing & Verification

  • Post your review as a GitLab issue one week before the in-team point-splitting.
  • Notify your tutor in person (before/after class) so they can verify and award any extra points.

Extra Points

Teams can earn up to 5 extra points for a helpful, constructive, and specific review. The reviewed team may optionally transfer up to 5 of their extra points to you if your review was especially useful.

Keep feedback firm, fair, and useful. Be honest without ego, specific without hostility, and remember there are many good ways to write clear docs—yours is one path among many.