# 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:

| Path | Purpose | Size |
|---|---|---|
| `README.md` | The entire guide (12 sections, 41 principles, ~2,386 lines) | Authoritative |
| `LICENSE` | MIT licence, Copyright © 2016 Ryan McDermott | 21 lines |
| `.gitattributes` | GitHub Linguist overrides for the `*.md` file | 2 lines |

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

```text
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:

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

| Attribute | Effect on GitHub |
|---|---|
| `linguist-documentation=false` | Overrides Linguist's default rule that `.md` files are documentation. Without this override, GitHub would mark the repo as 100% Documentation and exclude it from language statistics. |
| `linguist-language=JavaScript` | Tells Linguist to classify `.md` files as JavaScript for the purpose of language percentage bars. |

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:

```text
# 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:**
```javascript
[good example]
```
**[⬆ back to top](#table-of-contents)**   (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.

---

_Generated May 2026 from ryanmcdermott/clean-code-javascript at 5311f64. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._