Design, test, refactor, review, estimate and run software the way professional teams do.

Software Engineering Practices

## Why it matters

As soon as more than one person works on a codebase, you need an agreement about how changes flow from a laptop to production. Without one, people sit on long-lived branches, merges turn into day-long conflicts, and nobody is sure what is in a release. A **branching strategy** and a **versioning scheme** are that agreement. This lesson explains the most common modern approach, **trunk-based development**, and **semantic versioning** (semver), the numbering scheme used by npm and most libraries.

## Long-lived branches and why they hurt

A popular older model, often called **Git Flow**, uses a `develop` branch, long-running `feature/*` branches, `release/*` branches and `hotfix/*` branches. It works, but it has a cost: the longer a branch lives apart from the main line, the more the two drift. When a three-week feature branch finally merges, it conflicts with everything else that landed in those three weeks, and the combined code has never been tested together. Integration problems are discovered late, when they are most expensive.

## Trunk-based development

In **trunk-based development**, everyone integrates into one main branch (the "trunk", usually `main`) at least once a day.

- **Short-lived branches.** A branch lives hours or a day or two, then merges through a pull request. Some teams commit straight to `main` with pair programming instead.
- **Small changes.** Each pull request is small enough to review in minutes.
- **Continuous integration (CI).** Every push runs the build and tests automatically. `main` must always be releasable; if CI breaks, fixing it is the team's top priority.
- **Feature flags for unfinished work.** Code for a half-built feature can merge to `main` hidden behind a flag that is off in production. You release when it is ready by flipping the flag, not by merging a giant branch.

```javascript
if (flags.isEnabled("new-checkout", user)) {
  return renderNewCheckout(cart);
}
return renderCheckout(cart);
```

A typical day looks like this:

```bash
git switch main && git pull
git switch -c fix-tax-rounding
# small change + test
git commit -am "fix(cart): round tax to cents"
git push -u origin fix-tax-rounding   # open a PR, CI runs, a teammate reviews
# merged the same day, then the branch is deleted
```

**Releases** in trunk-based development are cut *from* trunk: either every merge deploys automatically (continuous deployment), or the team tags a commit on `main` and deploys that tag. If a release needs an urgent fix, the fix goes to `main` first and is then cherry-picked to a short release branch if one exists.

Feature flags have a cost too: every flag is a branch in the code. Remove a flag once the feature is fully launched.

## Semantic versioning

Software that other code depends on (libraries, APIs, apps with public release notes) needs version numbers that say what changed. **Semantic versioning** uses `MAJOR.MINOR.PATCH`, for example `2.4.1`:

| Change | Bump | Example |
|---|---|---|
| Breaking change: existing callers may need to change their code | MAJOR | `2.4.1 -> 3.0.0` |
| New feature that is backward compatible | MINOR | `2.4.1 -> 2.5.0` |
| Backward-compatible bug fix | PATCH | `2.4.1 -> 2.4.2` |

Rules worth remembering:

- When you bump a number, reset the ones to its right to zero: `2.4.1` plus a new feature is `2.5.0`, not `2.5.1`.
- `0.y.z` means "initial development": anything may change at any time, and many tools treat a minor bump as possibly breaking.
- Pre-releases use a hyphen: `3.0.0-beta.1` sorts *before* `3.0.0`.
- Removing a function, renaming a field in an API response or making an optional parameter required are all **breaking** changes, even if they feel small.

npm uses semver ranges in `package.json`. `"^2.4.1"` accepts any `2.x.y` at or above `2.4.1` (no new major). `"~2.4.1"` accepts only `2.4.x` patches. The **lock file** (`package-lock.json`) records the exact versions installed, so every machine and CI run gets the same ones.

Teams often generate versions and changelogs from commit messages that follow **Conventional Commits** (`feat:` means minor, `fix:` means patch, `BREAKING CHANGE:` or `feat!:` means major), which ties the two halves of this lesson together.

## Common mistakes

- Branches that live for weeks "until the feature is done".
- Merging to `main` with CI red, or ignoring a broken build.
- Releasing a breaking change as a minor or patch version.
- Forgetting to remove feature flags after launch.
- Deleting the lock file to "fix" an install problem, which silently upgrades dependencies.

## Recap

- Trunk-based development: small, short-lived branches merged to `main` daily, CI on every push, flags for unfinished work.
- Releases are cut from trunk; fixes land on `main` first.
- Semver: MAJOR for breaking changes, MINOR for compatible features, PATCH for compatible fixes.


Use trunk-based development with small, short-lived branches and version releases with semver.

Branching and releases

Continuous Integration vs Feature Branch Workflow

What is Semantic Versioning? (semver)

Pick a small feature for a project of yours (or the API you built in Back-End Web APIs), for example "users can bookmark items" or "rate-limit the login route".

Create a new repository on GitHub (or use an existing one), clone it, and on `main` add a `docs/` folder. Commit and push.

Create a short-lived branch: `git switch -c design-bookmarks` (use your own name for the feature).

Write `docs/design-<feature>.md` using the template from the reading: context, goals, non-goals, proposal, at least two alternatives considered, risks and open questions, rollout and testing. Keep it under two pages.

Commit with a clear message, push the branch, and open a pull request. In the description, say what you want reviewers to focus on.

Get a review: ask a friend, classmate or study-group member to comment on the PR. If nobody is available, wait a day and review it yourself using the five-point checklist from the reading, leaving at least three comments on specific lines.

Reply to every comment: change the doc where you agree, and explain your reasoning where you do not. Mark optional suggestions as resolved once handled.

Record the final decision in the doc (status: Accepted, plus one line on what changed during review), then squash-merge the PR and delete the branch.

## Why it matters

Two habits separate teams that ship reliably from teams that keep reworking the same features: they **review code** before it merges, and they **write down designs** before building anything large. Both are about catching problems while they are cheap. A mistake found in a one-page design doc costs an hour of discussion. The same mistake found after three weeks of code costs three weeks. Code review and design docs are also how knowledge spreads, so no single person is the only one who understands a part of the system.

## Code review

A **pull request** (PR, called a merge request on GitLab) proposes a change and asks teammates to review it before it joins `main`.

**As the author:**

- Keep PRs small: a few hundred changed lines at most. Large PRs get skimmed, not reviewed.
- Write a description that says *what* changed, *why*, and *how you tested it*. Link the issue.
- Review your own diff first. You will catch leftover debug code and typos.
- Separate refactors from behaviour changes, ideally in separate PRs.

**As the reviewer, look for:**

1. **Correctness:** does it do what the description says, including edge cases and errors?
2. **Tests:** is the new behaviour tested, and would the tests fail if the code were wrong?
3. **Design:** is it in the right place, and is it simpler than it could be?
4. **Security and data:** input validation, secrets, permissions, personal data in logs.
5. **Readability:** names, comments that explain *why*, consistent style (leave pure formatting to a linter).

**Write comments that are kind and specific.** Comment on the code, not the person. Ask questions when you are unsure ("What happens here if `items` is empty?"). Mark optional suggestions clearly, for example with a `nit:` prefix, so the author knows what blocks the merge and what does not. Approve when the change makes the codebase better, even if it is not exactly how you would have written it.

## Design docs

A **design doc** (also called a technical design document or RFC) describes a change before it is built, so others can review the approach. Not every change needs one. Write one when the work will take more than a few days, touches several components or teams, changes a data model or public API, or has a choice between options that are hard to reverse.

A short design doc template that works:

```markdown
# Saved searches for job listings

**Author:** Sam Rivera · **Status:** In review · **Reviewers:** Priya, Jon

## Context
Users repeat the same search every day. Support gets ~20 requests a month for alerts.

## Goals
- Users can save up to 10 searches and re-run them in one click.
## Non-goals
- Email alerts (a later project).

## Proposal
New `saved_searches` table (user_id, name, query JSON, created_at).
Endpoints: GET/POST/DELETE /api/saved-searches. Limit 10 per user, enforced in the API.

## Alternatives considered
- Store in browser localStorage: no cross-device sync, so rejected.

## Risks and open questions
- Query JSON format may change when filters change: version it (`v: 1`).

## Rollout and testing
Behind a feature flag; unit tests for the limit; enable for staff, then 10%, then all.
```

The most valuable sections are usually **non-goals** (they stop scope from growing) and **alternatives considered** (they show you chose deliberately and let reviewers suggest a better option before code exists). Keep it short: one to three pages. A design doc is a tool for a conversation, not a contract. Share it, collect comments, update it, and record the final decision.

Many teams also keep **architecture decision records** (ADRs): one short file per significant decision ("We use PostgreSQL for job data because..."), stored in the repository so the reasoning survives after people move on.

## Working together on the doc

- Share the doc early, while it is still easy to change your mind.
- Ask specific reviewers for specific input ("Priya, does the API shape fit the mobile app?").
- Resolve comments in the doc itself, or meet briefly when a thread goes back and forth more than twice.
- When the code is built, link the PRs from the doc, and note any places where the design changed.

## Common mistakes

- Thousand-line PRs with a one-word description.
- Reviews that only nitpick style while missing a logic bug.
- Comments that sound like personal criticism.
- Design docs written after the code, just for the record.
- Design docs with no alternatives, which usually means only one option was considered.

## Recap

- Small PRs with a clear what, why and how-tested; reviewers check correctness, tests, design, security and readability.
- Be kind and specific; label optional suggestions.
- Write a short design doc for big or hard-to-reverse changes: context, goals, non-goals, proposal, alternatives, risks, rollout.

## Try it

In the **Do** tab, write a one-page design doc in a GitHub repository, open a pull request for it and run a review.


Review pull requests well and write a short design doc that others can comment on before you build.

Reviews and design docs

What Is A Design Doc In Software Engineering? (full example)

Write one sentence describing the feature and what "done" means (including tests and deployment, if any).

Break it into tasks of about one day or less. Include tests, review, documentation and deployment, not just coding.

Give every task an optimistic, most-likely and pessimistic estimate in hours, and compute the PERT expected value `(O + 4M + P) / 6` for each and for the total.

List the top two risks (things that would push you towards the pessimistic number) and how you will find out early whether each one is real.

Write a three-to-five sentence status message for a manager: a range, your assumptions, the main risk and when you will know more.

Write down one shortcut you could take to finish sooner, the technical debt it would create, and when you would pay it back.

Do the work, logging the actual hours per task in the same table.

When you finish, compare estimates with actuals: calculate actual total divided by expected total, and note which tasks were furthest off and why.

## Why it matters

"How long will this take?" is one of the most common questions an engineer hears, and one of the hardest to answer well. Managers, designers and other teams plan around your answer: launch dates, marketing, hiring, who works on what next. A good estimate is not a promise of an exact date. It is an honest statement of **scope, uncertainty and risk** that helps other people make decisions. Learning to give one, and to explain the trade-offs behind it, builds more trust than being fast.

## Why estimates go wrong

- **Unknown work.** The task you are estimating is never quite the task you end up doing. Edge cases, reviews, tests, deployment and bug fixes are easy to forget.
- **Optimism.** People estimate the happy path: the time it takes if nothing goes wrong.
- **Anchoring.** Someone says "this should be quick, right?" and your estimate bends toward it.
- **Interruptions.** Meetings, on-call duty and code reviews take real hours from every week.

## Break the work down

Large tasks are impossible to estimate; small tasks are merely hard. Split the feature until each piece is about a day or less, and include the parts people forget.

Example: "Users can export their order history as CSV."

| Task | Estimate (days) |
|---|---|
| API endpoint that streams orders as CSV | 1 |
| Escape commas, quotes and newlines; handle 10,000+ rows | 0.5 |
| Button and download on the orders page | 0.5 |
| Unit and integration tests | 1 |
| Code review and fixes | 0.5 |
| Deploy behind a flag, check logs, enable | 0.5 |
| **Total** | **4** |

## Show the uncertainty: three-point estimates

Instead of one number, give three for each task: **optimistic** (O), **most likely** (M) and **pessimistic** (P). A common way to combine them is the PERT formula:

```text
expected = (O + 4M + P) / 6
```

For the whole export feature, suppose O = 3 days, M = 4 days, P = 9 days (the pessimistic case is that the orders table is too slow to export and needs a new index or a background job):

```text
expected = (3 + 16 + 9) / 6 = 28 / 6 ≈ 4.7 days
```

The gap between 3 and 9 is information. It tells the listener there is a specific risk, and what it is.

## Communicate scope and risk

How you say it matters as much as the number. A clear status message has a range, the assumptions behind it, the main risk and what you will do about it:

> Export to CSV: about 4–6 days, with 5 as my planning number. This assumes we export only the fields shown on the orders page. The main risk is query speed for large accounts; I'll test that on day 1 and tell you by Wednesday if we need a background job, which would add 3–4 days.

Practical habits:

- **Give ranges, not points**, and say what would move you to the top of the range.
- **Separate effort from calendar time.** Four days of work may take seven calendar days with reviews, meetings and on-call.
- **Re-estimate early and say so.** "I found X; the estimate is now 7–8 days" on day 2 is welcome. The same news on the due date is not.
- **Track your estimates against actuals.** After a few projects you will learn your own bias (most people are low by 1.5 to 2 times).

## Trade-offs: scope, time and quality

When the estimate does not fit the deadline, there are only a few levers: **reduce scope**, **move the date**, or **add people** (which rarely helps late in a project: new people need onboarding, and coordination costs grow). Cutting testing or review looks like a fourth lever, but it borrows time from the future.

That borrowing is called **technical debt**: a shortcut that saves time now and costs extra time later, like interest on a loan. Some debt is a reasonable business decision ("ship the simple version for the conference; replace the polling with webhooks next sprint"). Make it deliberate and visible:

- Write it down as a ticket, with the cost of leaving it.
- Agree when it will be paid back.
- Bring it up in planning when it starts to slow the team ("Every change to checkout takes two extra days because of the duplicated pricing code").

## Common mistakes

- Estimating only the coding, not tests, review and deployment.
- Giving a single number with no assumptions.
- Saying yes to a date you do not believe, then working weekends to hit it.
- Hiding bad news until the deadline.
- Treating all technical debt as bad, or all of it as fine.

## Recap

- Break work into small pieces, including tests, review and deploy.
- Use ranges or three-point estimates; the spread shows the risk.
- State assumptions, the main risk and when you will know more.
- Scope, date and quality are the levers; technical debt is a loan, so record it and plan the repayment.

## Try it

In the **Do** tab, estimate a real feature, write a status message and track how your estimate compares with reality.


Break work down, estimate with ranges, and communicate scope, risk and technical debt honestly.

Estimates and trade-offs

How To Estimate Software Development Time

What is technical debt?  Definition, Overview, and Best Practices

Integrate through trunk-based development and semantic versioning, review code and design docs, and communicate estimates, scope and risk.