Foundations: Python, Git and toolsLoading progress…
F6.5 · LESSON 5 OF 6

Review and documentation

Use a remote, pull request and automated check to propose a reviewable change.

THE IDEA

What a review is for

Review asks three questions, in this order of importance:

  • Is it correct? Does it do what the description says, including the edge cases? Run the numbers: a discount that divides by 10 instead of 100 compiles, passes a glance and charges the wrong price.
  • Is it understandable? Could someone who did not write it follow it in a year? Names, comments that explain why, no leftover debug output.
  • Is it maintainable and safe? No secrets in the repository, no copy-pasted logic, tests for new behavior.

Style taste comes last, and is best left to a formatter. A useful comment names the line, says what is wrong and why, and suggests a direction. Approving means "I would be comfortable owning this", not "I skimmed it".

Do"This divides by 10, so a 10 percent discount takes off the whole price. Should it be 100?" (specific line, reason, question)
Don't"This looks wrong." or "I would have written it differently." (no line of reasoning to act on)

Predict first. A reviewer finds an API_KEY value typed into the source. Which reviewer action is right?

Documentation is part of the change

A README answers a stranger's first questions: what is this for, how do I set it up, what does using it look like, and what configuration does it need? Listing technologies ("built with Node") answers none of them. Name every environment variable the code reads and show a safe sample value, so nobody has to infer names from error messages and nobody pastes a real secret into the docs.

  • ○ Purpose: say what the project is for in a sentence a stranger understands (not just a list of technologies) (For example: Pricing calculates discounts for the shop checkout.)
  • ○ Setup: a heading such as Install or Setup followed by a code block with the real commands (## Install, then a fenced block with npm ci.)
  • ○ Example: a heading such as Example or Usage with a runnable code block (Show a call such as discount(1000, 10).)
  • ○ Environment: name the variable the code needs (API_KEY) with a SAFE sample value, never a real secret (API_KEY=replace-me-with-your-key)
This README only lists a technology. Fix it until all four checks pass.
Chapter context

GitHub hosts repositories and adds collaboration around Git objects. A pull request is a review and discussion mechanism; the commits and branch history still follow Git rules.

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

For independent jobs with durations t1 and t2 running simultaneously, ideal elapsed time is max(t1,t2), excluding startup and queueing. A dependency adds a sequential edge and can make durations add instead.

Worked example

A build takes 3 minutes. Two test jobs taking 4 and 6 minutes start after the build and run together. The ideal critical path is 3 + max(4, 6) = 9 minutes, not 13. Real runners can add scheduling overhead.

Reference code

The following example uses the Python standard library and does not call a remote service.

build, tests = 3, [4, 6]
assert build + max(tests) == 9
assert build + sum(tests) == 13

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

A green check is evidence for the checks that ran, not proof of every behavior. Forked code must not automatically receive trusted secrets.