clean-code-javascript Admin Guide

Maintainer, contributor, and fork-owner documentation for Ryan McDermott's clean-code-javascript reference.

1. Executive Summary

clean-code-javascript is a single-document reference project. The entire product is one file — README.md — that distils Robert C. Martin's Clean Code principles into JavaScript examples. There is no runtime, no build step, no dependencies, no test suite, no CI pipeline, no release process beyond "push to master and rely on GitHub's CDN to serve the rendered Markdown."

The repository consists of exactly three tracked files:

This Admin Guide documents:

• Repository architecture — why the project is structured as a single README, and how the .gitattributes overrides shape its public presentation on GitHub.
• Editorial conventions — the Markdown patterns every principle follows, so contributors can submit consistent pull requests.
• Contribution workflow — how new principles, corrections, and translations are accepted.
• Maintenance posture — what kind of activity is on the tracker, what gets closed or ignored, and what the long-term stance is.
• Fork-owner guidance — how to run a derivative (e.g. clean-code-python) without reinventing structure.

Important

There is no software in this repository. Traditional administrative concerns — deployment, secrets, scaling, monitoring, logging — do not apply. What does apply is editorial governance: how edits are proposed, how translations stay linked, how the canonical structure is preserved across forks.

2. Repository Architecture

2.1 File Layout

clean-code-javascript/
├── .gitattributes     GitHub Linguist classification overrides
├── LICENSE            MIT licence, © 2016 Ryan McDermott
└── README.md          The entire reference guide

Three files. That is the complete tree. There is no src/, no docs/, no build/, no .github/workflows/ directory. Any documentation infrastructure (issue templates, contribution guidelines, code of conduct) is absent — contribution happens via direct pull requests against master.

2.2 The .gitattributes Trick

The two-line .gitattributes file is load-bearing for how GitHub presents the repository:

*.md linguist-documentation=false
*.md linguist-language=JavaScript

The combined effect: GitHub's repository page shows "100.0% JavaScript" in the language sidebar even though there is no executable JavaScript in the repo. This is an intentional editorial choice — the repository is about JavaScript, and the badge communicates that at a glance.

Note

If you fork this repo to build a language-specific derivative (e.g. clean-code-python), change the linguist-language value to match: *.md linguist-language=Python. Otherwise your Python guide will show up as JavaScript on GitHub.

Caution

Do not remove .gitattributes when forking. Without it, GitHub classifies the repository as pure documentation and the language sidebar disappears. The overrides are the difference between "a doc repo" and "the canonical JavaScript Clean Code reference" in GitHub's UI.

2.3 Document Architecture of README.md

The README itself has a consistent internal architecture that every contributor must follow. The structure is:

# clean-code-javascript              (H1, once, top of file)

## Table of Contents                 (H2, hand-maintained, 12 entries)
1. [Introduction](#introduction)
2. [Variables](#variables)
...
12. [Translation](#translation)

## Introduction                      (H2, prose only, no code)
...

## **Variables**                     (H2, bold, 7 principles)
### Use meaningful and pronounceable variable names   (H3, principle title)
[1-paragraph rationale]
**Bad:**                             (bold label, no heading)
```javascript
[bad example]

Good:

[good example]

⬆ back to top (navigation back-link)

[next principle] (H3, principle title)

...

Functions (next H2 category)

...

Every category is H2. Every principle is H3 under its category. Every
principle ends with the `**[⬆ back to top](#table-of-contents)**`
back-link. No H4 headings exist in the document.

> [!TIP]
> The back-link on every H3 is what makes a 2,386-line document
> navigable. If a contributor submits a new principle without the
> back-link, reject or fix before merging.

### 2.4 Code-Block Conventions

All code blocks use fenced syntax with the `javascript` language tag:

````markdown
```javascript
const currentDate = moment().format("YYYY/MM/DD");

No inline `console` output blocks appear — Good examples implicitly
assume the reader can reason about what the code produces. No
shell/Node commands are shown; the guide is language-theoretical, not
operational.

### 2.5 Translation Section Conventions

The `## Translation` section at the end of the README is a manually
curated list. Each entry is:

```markdown
- ![xx](<flag-image-url>) **<Language Name>**: [<fork-slug>](<fork-url>)
```

Flag images are pulled from the `gosquared/flags` repository's shiny-24px
PNG set. The alt text is the two-letter country code.

> [!NOTE]
> Do not inline the flag images from the author's own repo —
> `gosquared/flags` is a separate well-known resource used by many
> multilingual documentation projects. Reusing the same image URLs
> keeps the flag rendering consistent across the ecosystem.

## 3. System Requirements

### 3.1 For Readers

None. Any modern browser pointed at
`https://github.com/ryanmcdermott/clean-code-javascript` renders the
entire guide. GitHub's Markdown renderer handles:

- Fenced code blocks with `javascript` syntax highlighting
- Anchor links from the Table of Contents to H3 principles
- Remote `gosquared/flags` images in the Translation section

For offline reading, any Markdown viewer that supports GitHub-Flavoured
Markdown will do:

| Viewer | Verified |
|---|---|
| VS Code built-in preview | Yes, including syntax highlighting |
| Typora | Yes |
| Obsidian | Yes |
| `glow` (terminal) | Yes, colours + paging |
| `mdcat` (terminal) | Yes |
| Browser + `markdown-preview` extension | Yes |

### 3.2 For Contributors

Minimum tooling to submit a correction or new principle:

- A GitHub account
- Any text editor that can save UTF-8 (the file contains Cyrillic,
  Chinese, Japanese, Korean, Arabic characters in the Translation
  section)
- `git` for forking + branch + PR workflow

Nothing else is required. No build step validates the README before
merge; no linter runs in CI. The author reviews pull requests manually.

### 3.3 For Fork Owners

If you fork to build a derivative (see Section 8), your only technical
requirement is choosing a canonical repository host (GitHub, GitLab,
Gitea, etc.). Most existing translations and derivatives are hosted on
GitHub, which makes cross-linking via the Translation section
straightforward.

## 4. Configuration Reference

There is no configuration. The only config-like file in the repo is
`.gitattributes`, documented in Section 2.2.

## 5. Security

### 5.1 Attack Surface

`clean-code-javascript` has no executable surface. It is a Markdown file
rendered by GitHub's static pipeline. There is no server, no
user-supplied input, no authentication, no secrets.

### 5.2 Content Risks

The one externally-referenced resource class is **remote images** in
the Translation section:

```markdown
![am](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Armenia.png)
```

If `gosquared/flags` were deleted, renamed, or compromised, the
Translation section's flag images would either 404 or serve replacement
content. The text labels (e.g. "**Armenian**:") and repository links
remain functional.

> [!NOTE]
> `gosquared/flags` has been stable for over a decade and is referenced
> by many multilingual projects. The probability of disruption is low,
> but it is the only upstream dependency worth auditing.

### 5.3 Links to Third-Party Repositories

The Translation section lists 20+ community forks. Each is an independent
repository controlled by its author; the original repo has no control
over their content. If a linked translation were maliciously modified —
for example, to include misleading advice — readers who follow the link
would see the modified version.

> [!WARNING]
> When adding a new translation link, verify that the linked
> repository's README substantively matches the English version's
> structure before accepting the contribution. An "off-structure"
> translation is less useful and harder to maintain.

### 5.4 Licence Compliance

The repository is MIT-licensed (`LICENSE`, Copyright © 2016 Ryan
McDermott). Forks must preserve the copyright notice.

Translators and derivative authors commonly add their own copyright
line below the original, e.g.:

```text
Copyright (c) 2016 Ryan McDermott
Copyright (c) 2020 [Translator Name]
```

This is permitted and expected under MIT.

## 6. Contribution Workflow

### 6.1 Proposing a Correction

Small corrections — typos, broken code in an example, factual errors —
are submitted as pull requests:

- [ ] Fork `ryanmcdermott/clean-code-javascript` on GitHub.
- [ ] Create a branch from `master`: `git checkout -b fix/spelling-variables`.
- [ ] Edit `README.md` with your correction.
- [ ] Preserve the section's H2/H3/back-link structure (Section 2.3).
- [ ] Commit with a descriptive message: `git commit -m "Fix typo in
      Variables: pronouncable -> pronounceable"`.
- [ ] Push and open a PR against `ryanmcdermott/clean-code-javascript:master`.

No contributor-licence agreement is required; MIT licensing is inherited.

### 6.2 Proposing a New Principle

A new principle is a higher-stakes change because it grows the
canonical document. Before opening a PR:

- [ ] **Verify it is not a duplicate.** Search existing H3 headings in
      the README for semantically similar rules. The Functions chapter
      already has 20 principles; many apparent gaps are covered.
- [ ] **Verify it is language-level, not framework-level.** React,
      Vue, Node.js, and Express idioms are out of scope. Rules that
      apply to vanilla ES2015+/ES2017+ are in scope.
- [ ] **Draft Bad and Good examples.** Both are required, both must
      be runnable, and both must be minimal. If your Good example is
      longer than 30 lines, you are probably solving too many problems
      at once.
- [ ] **Pick the correct H2 category.** Do not add new H2 categories
      without opening an issue first; the 11 categories map to the
      structure of the source book and re-partitioning is a large edit.

### 6.3 Proposing a Translation

Translations are handled differently from other contributions. A
translated README lives in a **separate fork**, not in the original
repository. The workflow:

- [ ] Fork `ryanmcdermott/clean-code-javascript`.
- [ ] Translate `README.md` in place on your fork's `master` branch.
      Keep the English file; do not create a `README.<lang>.md` — the
      convention is one README per repo.
- [ ] Commit with `git commit -m "Initial translation to <language>"`.
- [ ] Open an **issue** on `ryanmcdermott/clean-code-javascript`
      requesting that your fork be linked from the Translation section.
      Do **not** open a PR against `master` containing the translated
      text.
- [ ] In the issue, include: target language, your fork's URL, and
      (optionally) the ISO country code you would like for the flag.

The maintainer adds a single line to the Translation section pointing
to your fork. Subsequent updates to your translation happen on your
fork — you do not need to coordinate with the upstream repo.

> [!IMPORTANT]
> This fork-based translation model is why `.gitattributes` exists and
> why the repo retains flat structure. If translations were sub-files
> (`README.es.md`, `README.zh.md`), maintenance would require the
> original author to review every language. The fork model delegates
> ownership to each translator.

### 6.4 Proposing a Derivative for Another Language

If you want to write `clean-code-python`, `clean-code-rust`, or similar,
do **not** open a PR against `ryanmcdermott/clean-code-javascript`.
Fork independently and:

- [ ] Retain the `LICENSE` file with the original copyright notice.
- [ ] Add your own copyright line if you wish.
- [ ] Update `.gitattributes` to reference the target language:
      `*.md linguist-language=Python`.
- [ ] Preserve the document architecture (Section 2.3) so readers
      familiar with the original can navigate yours instantly.
- [ ] Delete principles that do not apply to your target language
      (e.g. `Object.assign`, ES2017 `async/await` in synchronous
      languages).
- [ ] Add principles that are specific to your target language, in
      the same H3 shape.

There is no "official" blessing process for derivatives. Existing
examples in the ecosystem — `clean-code-python`, `clean-code-php`,
`clean-code-typescript`, `clean-code-dart` — were all created
independently using this pattern.

## 7. Operations

### 7.1 Day-to-Day Maintenance

Because there is no runtime, "operations" consists of editorial
triage. The typical cadence, judging from the issue tracker and
commit history:

| Activity | Frequency | Notes |
|---|---|---|
| Reviewing small-fix PRs | Irregular, as submitted | Typo fixes, broken example fixes |
| Adding translation links | On issue request | Append to Translation section |
| Adding new principles | Rare | Structural change; requires discussion |
| Closing off-topic issues | As needed | Tracker accumulates noise (see 7.2) |

### 7.2 Issue Tracker Signal-to-Noise

The issue tracker receives a non-trivial volume of **off-topic posts**:
Kotlin source files, Russian-language essays, and unrelated code
snippets posted as "issues" by confused users. Identifying signal
(corrections, translation offers, substantive principle proposals)
requires scanning titles.

Representative on-topic open issue at time of writing:

- `#705` — *Update `Object.assign()` example to include modern spread
  operator alternative*. The `Set default objects with Object.assign`
  principle in the README still uses ES2015-era syntax; a spread-based
  equivalent (`{ ...defaults, ...config }`) is now idiomatic. This is
  a legitimate correction candidate.

Representative off-topic open issues at time of writing:

- `#714` *SceneManager.kt*, `#713` *SmartDevice.kt*, `#712`
  *MainActivity.kt* — Kotlin source files posted to a JavaScript repo.
- `#711`, `#710`, `#715`, `#716` — Russian-language posts unrelated to
  the guide.

> [!TIP]
> If you take over maintenance of this repo or a derivative, create a
> `.github/ISSUE_TEMPLATE/` directory with two templates: "Propose a
> correction" and "Request a translation link". Templates filter out
> most noise automatically because authors of off-topic posts rarely
> follow the prompts.

### 7.3 Release Process

There is no release process. Commits to `master` are immediately live
on `github.com/ryanmcdermott/clean-code-javascript`. There are no
tags, no GitHub releases, no versioned published artefacts.

> [!NOTE]
> The repository has no versioning because every reader always sees
> the latest `master`. Forks and translations pull at the time they
> were forked and drift from upstream unless the translator
> periodically rebases. This is a deliberate tradeoff: low maintenance
> burden at the cost of translation drift.

### 7.4 Link Rot Management

Over time, external links in the README decay:

- Referenced tools move or rename (`gotwarlost.github.io/istanbul/`
  → migrated to `istanbul.js.org/` or superseded by `c8`).
- Community translation forks go unmaintained, rename, or delete.
- Images at `osnews.com/images/comics/wtfm.jpg` could disappear.

Recommended periodic maintenance (every 6–12 months):

- [ ] Run a Markdown link-checker over `README.md`. Community tools:
      `markdown-link-check`, `lychee`.
- [ ] Verify each Translation fork URL still resolves and has a
      non-empty README.
- [ ] Verify the opening WTF-per-minute comic image still loads.
- [ ] Update the three tool references (`buddy.js`, `ESLint`,
      `istanbul`) if any has been superseded.

The repository has no CI to automate this, so it must be done
manually or in a local cron job.

### 7.5 Backup and Recovery

GitHub is the source of truth. For disaster recovery, the complete
repository is under 50 KB — any contributor's local clone is a full
backup.

```bash
git clone https://github.com/ryanmcdermott/clean-code-javascript.git
```

```text
Receiving objects: 100% done.
Resolving deltas: 100% done.
```

If GitHub itself became unavailable, any community fork can be
promoted to canonical by a maintainer. The `LICENSE` file explicitly
permits this.

## 8. Running a Derivative

This section is for developers who want to publish their own
`clean-code-<language>` or `clean-code-<framework>` guide modelled on
Ryan McDermott's structure.

### 8.1 Canonical Structure to Preserve

Preserve these structural elements — they are what makes the format
recognisable and scannable across derivatives:

- [ ] **One H1** at the top, matching the repo name.
- [ ] **Table of Contents as numbered list**, with each entry linking
      to a category anchor.
- [ ] **`## Introduction`** as H2, prose only, no code.
- [ ] **Each category as `## **Category Name**`** — yes, H2 with
      bold markup inside. This is the document's signature.
- [ ] **Each principle as H3** under its category.
- [ ] **Bad/Good pair** labelled as **bold text**, not headings.
- [ ] **`**[⬆ back to top](#table-of-contents)**`** after every
      principle.
- [ ] **Translation section at the end**, even if empty at first.

### 8.2 Structure You Can Change

- Category list — add, remove, or rename to fit your language. Go
  derivatives often remove SOLID (because Go has no classes in the
  OO sense); Python derivatives usually keep it.
- Principle count per category — some languages have many fewer
  function-naming rules because the ecosystem already enforces them
  via standard tooling.
- Example libraries — use your language's idiomatic stdlib and
  ecosystem; don't port `moment`/`lodash` metaphors literally.

### 8.3 Hosting Checklist

- [ ] Public GitHub (or GitLab) repository.
- [ ] MIT or compatible licence (attribute the original author).
- [ ] `.gitattributes` updated for your target language's Linguist
      code.
- [ ] Repository `About` description mirroring Ryan's format
      ("Clean Code concepts adapted for <Language>").
- [ ] Optional: a link back to the JavaScript original in your
      `## Introduction` for historical credit.

### 8.4 Minimal Tooling

Once published, minimal maintenance tooling:

| Tool | Purpose | Optional |
|---|---|---|
| `markdown-link-check` or `lychee` | Periodic link-rot scan | Recommended |
| `markdownlint` with `MD001`/`MD003` relaxed | Style linting | Optional; the H2-with-bold format will trip some defaults |
| Dependabot / Renovate | Dependency upgrades | Not applicable — no dependencies |
| GitHub Actions | CI | Only if you add link-check or linting |

## 9. Troubleshooting

### Error: "Table of Contents anchors don't work for one of my categories"

**Cause.** GitHub's anchor slug generator lowercases, strips
punctuation, and replaces spaces with hyphens. For categories with
special formatting (e.g. `## **Objects and Data Structures**`), the
emitted anchor is `#objects-and-data-structures` — the asterisks are
stripped, not preserved.

**Solution.** Manually test every Table of Contents link after an
edit. Open the rendered README on GitHub and click each entry; if any
fails, the H2 heading's slugification differs from the anchor you
wrote in the TOC.

**Prevention.** Follow the existing category naming pattern exactly.
Avoid slashes, parentheses, and ampersands in new H2 category titles.

### Error: "Linguist still shows my fork as documentation despite the `.gitattributes` override"

**Cause.** GitHub caches Linguist results. A pushed change to
`.gitattributes` does not immediately update the language sidebar.

**Solution.** Wait up to 24 hours for the cache to refresh, or push
any additional commit to force re-analysis. For long-lived caches,
open an issue on `github/linguist` with the repo URL.

**Prevention.** Set `.gitattributes` correctly on the initial fork
commit so the first Linguist run classifies the repository properly.

### Error: "A translation fork I linked is now 404 / empty / stale"

**Cause.** Translation forks are owned by independent authors. They
sometimes abandon or delete their repositories.

**Solution.** Remove the stale link from the Translation section.
If a replacement fork in the same language exists, link it instead;
otherwise leave the slot empty so readers aren't misled.

**Prevention.** Run a link-check pass every 6–12 months (see
Section 7.4).

### Error: "A Good example I copied into production fails my linter"

**Cause.** The Good examples illustrate the *specific principle*
being taught. They are not meant to be lint-clean against every
modern ESLint ruleset. Some examples omit `const` in favour of `let`
to focus the reader's attention; some use `function` declarations
rather than arrow functions because the principle predates ES2017
conventions.

**Solution.** Apply the principle, then run your linter and fix
secondary violations. The guide teaches *shape*; your linter
teaches *polish*.

**Prevention.** Don't paste Good examples directly into production
code. Copy, adapt, run the linter, commit.

### Error: "My PR adding an H4 sub-heading was rejected"

**Cause.** The document is intentionally two-level within principle
sections. Each principle is one H3 with prose plus Bad/Good blocks.
Sub-headings inside a principle break the scan-reading rhythm.

**Solution.** Rework the content to fit within a single H3. If the
principle genuinely has multiple independent parts (as `Avoid Side
Effects (part 1)` and `(part 2)` do), split it into two adjacent H3
principles instead of nesting with H4.

**Prevention.** Read five random principles in the existing README
before drafting a new one. Match their shape.

### Error: "I cannot install `request` / `request-promise` / `fs-extra` shown in examples"

**Cause.** The Concurrency examples reference packages that are now
deprecated. `request` has been unmaintained since 2020; `request-promise`
and `fs-extra` are similarly aged.

**Solution.** Substitute modern equivalents when adopting the
pattern:

```javascript
// Old (README example):
import { get } from "request-promise";
import { writeFile } from "fs-extra";

// Modern:
import fs from "node:fs/promises";
const body = await fetch(url).then(r => r.text());
await fs.writeFile("article.html", body);
```

**Prevention.** When reading code in the guide, focus on the
*pattern* (Promises vs callbacks, async/await vs Promise chains)
rather than the specific packages. The principles are language-level
and outlast any package.

## 10. Code Quality and Conventions

### 10.1 Document-Level Conventions

| Convention | Rationale |
|---|---|
| One H1 at top | Standard Markdown; GitHub renders as page title |
| Bold-wrapped H2 category titles (`## **Variables**`) | Visual distinction from the Introduction's plain H2 |
| Every principle ends with `[⬆ back to top]` | Navigable long-form document |
| Bad before Good | The Bad example establishes the problem; the Good example resolves it |
| No emoji in headings | Universal screen-reader and terminal compatibility |
| No nested code fences | GitHub renders nested fences unreliably |
| Fenced blocks always tagged `javascript` | Syntax highlighting + copy-paste reliability |

### 10.2 Prose Style

The README uses:

- **Second person** ("you can...", "your functions...").
- **Active voice** ("Getting the abstraction right is critical").
- **Informal registers** including occasional humour ("accidentally
  wiring all your money to a stranger").
- **No footnotes or citations** — referenced works are hyperlinked
  inline.

Contributors should match this tone. Do not submit principles written
in third person or in formal academic prose.

### 10.3 Example Style

Examples follow these conventions:

- **Use semicolons.** The Bad and Good examples both terminate
  statements explicitly.
- **Use double quotes for strings.** Consistent throughout.
- **Use arrow functions inside callbacks** (`forEach(location => {...})`)
  but prefer `function` declarations for top-level named functions.
- **Destructure in function signatures** when the principle calls
  for it; do not over-destructure elsewhere.
- **Show imports explicitly** for Concurrency examples
  (`import { writeFile } from "fs-extra"`). This makes the
  dependency obvious.

> [!TIP]
> When writing new examples, hold them to "minimal viable
> demonstration". An example that introduces two concepts at once
> forces the reader to untangle them — defeating the principle's
> teaching goal.

## 11. Potential Improvements

The following are live observations from the repository state and
open issues as of the generation date. They are suggestions, not
commitments from the maintainer.

| # | Observation | Impact |
|---|---|---|
| 1 | Modernise `Object.assign` example with spread syntax (tracked as issue #705). | Small; one example. |
| 2 | Add a principle on **optional chaining** (`?.`) and **nullish coalescing** (`??`) — both became available in ES2020 and replace whole classes of guard patterns. | Medium; new principles in Variables or Functions. |
| 3 | Add a Concurrency principle on **`AbortController`** for cancellable async work. | Medium; notable gap for modern Node/browser code. |
| 4 | Replace deprecated `request` / `request-promise` / `fs-extra` in examples with native `fetch` and `fs.promises`. | Small per example but touches multiple principles. |
| 5 | Add an H2 section on **TypeScript migration** — the existing *Avoid type-checking (part 2)* suggests TypeScript without showing how. | Medium; structural addition. |
| 6 | Convert the Table of Contents from a numbered list to a table so it renders in GitHub's file-level preview. | Cosmetic. |
| 7 | Add `.github/ISSUE_TEMPLATE/` with templates for corrections and translation requests. Reduces off-topic issue volume (see 7.2). | Operational; low effort. |
| 8 | Add a `CONTRIBUTING.md` pointing at Section 6 of this Admin Guide or similar. | Operational; reduces first-time-contributor friction. |
| 9 | Add a `.markdownlint.yaml` to formalise the document conventions in Section 10.1 so contributors cannot accidentally break the format. | Operational; requires some relaxation of defaults. |
| 10 | Private class fields (`#field`) are now standardised; the *Make objects have private members* principle could be updated to show both the closure pattern and the modern syntactic pattern. | Small; one example extended. |

## 12. Quick Reference

### 12.1 Repository Facts

| Attribute | Value |
|---|---|
| Canonical URL | `https://github.com/ryanmcdermott/clean-code-javascript` |
| Licence | MIT |
| Copyright | © 2016 Ryan McDermott |
| Tracked files | 3 (`README.md`, `LICENSE`, `.gitattributes`) |
| Lines in `README.md` | 2,386 |
| Principle categories | 11 + Translation |
| Total principles | ~41 (varies slightly by how "parts" are counted) |
| Translations linked | 20+ language forks |
| Last substantial update | 2023-02-11 (commit `5311f64`) |
| CI / build / tests | None |
| Runtime dependencies | None |
| Dev dependencies | None |

### 12.2 Category → Principle Count

| Category | Principles |
|---|---|
| Variables | 7 |
| Functions | 20 |
| Objects and Data Structures | 2 |
| Classes | 3 |
| SOLID | 5 (SRP, OCP, LSP, ISP, DIP) |
| Testing | 1 (Single concept per test) |
| Concurrency | 2 (Promises over callbacks; async/await over Promises) |
| Error Handling | 2 (Don't ignore caught errors; Don't ignore rejected promises) |
| Formatting | 2 (Consistent capitalization; Callers and callees close) |
| Comments | 4 (Only business-logic comments; no commented-out code; no journal comments; no positional markers) |

### 12.3 Contributor Checklist

Before opening a PR:

- [ ] Change affects `README.md` only (or `.gitattributes` with a documented reason).
- [ ] New H3 principle (if any) has prose + Bad + Good + back-link.
- [ ] Table of Contents updated if a new H2 category was added.
- [ ] All code blocks use `javascript` language tag.
- [ ] Examples use semicolons and double quotes.
- [ ] PR description explains *why* the principle belongs in the guide (not just what it says).

### 12.4 Fork Owner Checklist

Before publishing a derivative:

- [ ] `LICENSE` retains Ryan McDermott's copyright line plus yours.
- [ ] `.gitattributes` updated to target language's Linguist code.
- [ ] Repository `About` description follows "Clean Code concepts adapted for <Language>" pattern.
- [ ] README preserves H1 / TOC / H2-category / H3-principle / back-link structure.
- [ ] Irrelevant principles removed (e.g. no `Object.assign` in a Go derivative).
- [ ] Language-idiomatic principles added.
- [ ] Existing derivatives in the target language audited — do not create a duplicate; offer to contribute instead.