Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 50 ยท Agile and Teamwork

Working in a Team: Reviews, Communication and Ownership

Learn how professional teams work together: code review practice, good pull requests, pair and mob programming, documentation and a blameless culture.

Most professional software is built by teams, and most of a developer's day is spent reading, discussing and changing code that other people wrote. The technical skills in the rest of this course matter, but a team with average tools and good habits usually beats a team of stars who cannot work together. This lesson covers the habits: how to review code, how to write a change others can review, how to work together in real time, what to write down, and how to talk about mistakes.

Teamwork is made of people and conversations, so most of this lesson is read-only: the pull request template and review comments below are plain text, not something you run. Two plain JavaScript stand-ins score a review against a checklist and flag unhelpful wording. They use invented data and are only illustrations; they are not a real review tool.

Why review code at all?

Code review means that someone other than the author reads a change before it becomes part of the shared code. Its benefits go beyond finding bugs:

  • Defects found early, when they are cheapest to fix.
  • Shared knowledge: at least two people understand each part of the system, so there is no single point of failure.
  • Consistency: the code base reads as if written by one team.
  • Mentoring: juniors learn from seniors' comments, and seniors learn from fresh eyes.
  • Design feedback before a design is set in stone.

What a review looks for

Correctness Does it do what it should?
Tests Are behavior and failures covered?
Safety Any security or data risk?
Clarity Can a newcomer follow it?

Style rules belong to automated tools, not to people.

1 / 2

Writing a change that is easy to review

A review is only as good as the change in front of the reviewer. A pull request (PR; on some platforms a merge request) is a proposal to merge a branch, with a place to discuss it. The author's job is to make the reviewer's job easy:

  1. Keep it small. Research and experience suggest that reviewers find far fewer problems in very large changes: after a few hundred lines, attention drops. Aim for a change that can be understood in 15 to 30 minutes. Split refactoring from behavior changes.
  2. Explain why, not only what. The diff shows what changed; the description should say why, what you considered, and how you tested.
  3. Review it yourself first. Reading your own diff on screen catches debugging leftovers and obvious mistakes.
  4. Let automation handle the boring parts. Formatters, linters and tests run in CI so humans can think about design and logic.

A short pull request description might look like this. It is a template, not code that runs:

TEXT
Title: Add coupon codes to checkout

Why
Marketing needs percentage coupons for the spring campaign (ticket SHOP-214).

What changed
- New Coupon model with code, percent, expiry date
- Checkout applies one coupon and shows the discount line
- Expired and unknown codes show an error message

How I tested it
- Unit tests for percentage and expiry rules
- Manually applied valid, expired and unknown codes in the staging environment

Out of scope
- Stacking several coupons (follow-up SHOP-231)

Notes for reviewers
- Please check the rounding in Coupon::apply()

Links to the Git side of this process live in the Git track; how pull requests fit into branches and pipelines comes up in version control, CI and delivery pipelines.

Giving and receiving feedback

The same sentence can help or hurt, depending on how it is phrased. Compare these review comments (read-only examples):

TEXT
Unhelpful:  "This is wrong."
Helpful:    "If the cart is empty, total() divides by zero on line 42.
             Could we return 0 in that case? A test would pin it down."

Unhelpful:  "You always forget error handling."
Helpful:    "The call on line 17 can fail when the network is down. What should
             the user see then?"

Unhelpful:  "Obviously this should be a map."
Helpful:    "A map keyed by id would make this lookup O(1) instead of scanning
             the list. Worth it here, or is the list always short?"

Good comments are specific (point at a line and a situation), explain the reason, suggest a way forward (or ask a question), and are honest about priority. Many teams prefix comments: blocker: must change before merge, suggestion: take it or leave it, nit: tiny style point, question: I want to understand. Praise good work too, because reviews that only criticize teach people to dread them.

When you are the author, remember that the review is about the change, not about you. Assume good intent, answer every comment (even with "done"), and explain your choices politely if you disagree. If a long thread develops, talk face to face or on a call and write the outcome in the PR.

Stand-in: a review checklist scorer

Many teams keep a short checklist so important questions are not forgotten. The stand-in below weights each question and gives a verdict: any unmet critical item means "request changes", otherwise unmet small items become "approve with comments". The weights and answers are invented.

JS Review checklist scorer

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A real review is a judgment call by a human; the numbers only make the team's priorities explicit.

Working together in real time

Review after the fact is one way to share knowledge. Others work together while writing:

  • Pair programming: two people, one task, one keyboard (see Kanban, XP and Lean). Useful for tricky logic, onboarding and spreading knowledge. Rotate pairs and take breaks.
  • Mob programming: the whole team works on one problem on one screen, with one driver typing and everyone else navigating. It looks expensive, but it removes handoffs and waiting for reviews, and it works well for design decisions, hard bugs and teaching.
  • Remote and asynchronous work: with people in different time zones, prefer written communication that can be read later (design notes, clear PR descriptions), and use meetings for decisions and discussion, not announcements.

Pair or mob work replaces part of the review, since someone already saw the code, but many teams still let a third person look at the change.

Documentation: write down what is expensive to rediscover

You cannot document everything, and documentation that is out of date is worse than none. Concentrate on what readers cannot easily get from the code:

  • README: what the project is, how to run, test and deploy it. A new person should get started from it in under an hour.
  • Architecture notes and decision records: why the system is shaped as it is (see architecture decisions).
  • API documentation: the contract that other people rely on.
  • Runbooks: what to do at 3 a.m. when an alert fires.
  • Comments in code: explain why, not what. The code already says what it does.

Keep documentation next to the code (in the repository), review it in pull requests, and delete what is no longer true.

Ownership and a blameless culture

Teams work best when ownership is clear but not exclusive. Individual code ownership ("this is Ben's module") creates bottlenecks and a single point of failure. Collective ownership means anyone may change any code, supported by tests and review. Many teams use a middle path: files list maintainers who must review changes, but anyone can propose them.

Mistakes will happen: outages, bad releases, security slips. How a team reacts decides whether it learns. In a blameless culture, an incident review (a post-mortem) asks how did the system allow this to happen? and not who did this? People who fear punishment hide problems; people who feel safe report them early. Blameless does not mean consequence-free or no accountability: it means that individuals are not made the cause of a failure that was really a gap in tests, process, tooling or knowledge. A good post-mortem ends with concrete actions: a missing alert, a missing test, a clearer procedure.

Wording matters here too, as the second stand-in shows. It scans comments for phrases that tend to sound like blame or dismissal and suggests a change. A handful of patterns can only catch some cases, and tone depends on context, so treat it as a toy, not as a policy tool.

JS Blameless wording check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Communication habits that scale

  • Write things down where others can find them (tickets, documents), not only in chat.
  • Make work visible: a board, short stand-ups, regular demos.
  • Ask early: fifteen minutes of asking beats a day of being stuck, and most teams prefer questions to silent struggling.
  • Disagree, then commit: argue about the decision with evidence, but once it is made, support it fully.
  • Be explicit about expectations: who decides, who reviews, by when.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which is the main reason to keep pull requests small?

    Review quality drops as changes grow. Small changes are easier to reason about and easier to undo if they cause trouble.
  2. 2. Which review comment is most helpful?

    A helpful comment is specific, explains the reason, suggests a direction and avoids judging the person.
  3. 3. What is the purpose of a blameless post-mortem?

    Blameless reviews focus on causes in the system, so people report problems early and the team fixes root causes.
  4. 4. What should code comments mostly explain?

    The code shows what it does; comments are most useful for intent, constraints and trade-offs. Change history belongs in version control.
  5. 5. How does mob programming differ from pair programming?

    In mob programming the whole team works together on a single piece of work, with one driver and many navigators.

Summary

  • Code review finds defects early, spreads knowledge and keeps the code consistent; automation should handle style so humans focus on logic and design.
  • Make changes easy to review: small, explained, self-reviewed, tested.
  • Good comments are specific, give a reason, suggest a way forward and critique the code, not the person.
  • Pair and mob programming share knowledge in real time; documentation should capture what is costly to rediscover and live next to the code.
  • Collective ownership backed by tests avoids bottlenecks; a blameless culture treats failures as system problems and ends with concrete actions.

Next: Testing Levels and Strategy.