30-Days-Of-JavaScript/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

这个仓库到底是什么

这里并存着两层内容:

1. 上游教程 —— NN_Day_* 文件夹(例如 01_Day_Introduction、 23_Day_Event_listeners),以及各语言翻译文件夹(Korea/、RU/、 Spanish/……)。这是 Asabeneh 的 "30 Days Of JavaScript" 课程,作为只读 参考资料克隆进来。不要修改或"修复"这些文件 —— 其中的错误(例如 main.js 依赖另一个单独加载的 variable.js 里的变量)是刻意为之的教学产物,不是 bug。

2. js_notes/ —— 用户自己的学习笔记,也是活跃工作区。 几乎所有真正的工作都发生在这里。它按知识主题组织,而非按天 (01-basics、02-variables、……07-objects……),因为这个编号反映的是 用户的学习顺序,而不是教程的天数。

用户是正在入门 JavaScript 的初学者(有一些 Python/Linux 背景)。 每次会话都是交互式辅导:讲一个主题、让用户练习、复审他的代码。

js_notes/ 的结构与约定

• 一个主题一个文件,平铺在 js_notes/ 根目录:NN-topic.js(例如 09-loops.js)。每个文件都自成一体,包含"学习 + 练习 + 复习",分为三个 带标签的区块,顺序如下:
  1. // ═════ 概念总结 ═════ —— 以注释形式呈现概念(含对齐的 ASCII 表格)
  2. // ═════ 示范 ═════ —— 可运行的演示代码,可带预期输出注释
  3. // ═════ 轮到你 ═════ —— 练习:只给要求,由用户自己写代码 js_notes/README.md 是索引 + 进度地图。
• 历史沿革: 主题过去是 NN-topic/ 文件夹,里面放 notes.md + practice.js;后来被扁平化为单个 NN-topic.js 文件。my-mistakes.md 里有些 📍来源 链接仍指向旧的 ../NN-topic/practice.js 路径 —— 请把它们视作 ../NN-topic.js(只在你本来就在编辑那条条目时才顺手修链接;不要对用户的文件 做一次性的全量重写)。
• js_notes/00-concepts/ 保持为一个文件夹,存放跨主题的 .md 笔记 (值 vs 引用、调用形式、bash-vs-js 短路、分号与 ASI),外加 my-mistakes.md —— 一份用户实际犯过的错误的滚动记录,每条采用 错法→现象→正解→教训 格式,并带一个指回原练习的 📍来源 反向引用。

js_notes/README.md 含有具有约束力的辅导规则 —— 教学前先读它。 其中最关键的几条:

• 不替用户写答案。 在练习文件里,"轮到你"区块只给要求 —— 不给解答, 连注释掉的解答也不行(那会破坏练习)。提示只指方向("这两个方法可以链式 调用"),不轻易给出完整的一整行,比如 raw.trim().toLowerCase()。
• 让用户自己修自己的代码。 指出哪里错了、为什么错;不要替他改练习答案。
• 演示区块(教学示例)可以用注释写出预期输出;练习区块不可以。
• 当用户犯了新错误时,把它吸收进 00-concepts/my-mistakes.md (错法→现象→正解→教训 格式,带 📍来源 索引);或者如果不值当单开一条,就直接在那个笔记里 Edit 也行,这样复习时可追溯。 但只记真正有教益的错误 —— 已被现有条目覆盖的纯手误,或用户已经自己 修好、没有新东西可学的错误,不值得新开一条(记流水账的话用户会反驳)。 拿不准时,问一下。
• 一个主题完成后,更新 js_notes/README.md 里的进度勾选框。

一章收尾必做清单(用户的长期要求)⭐

当一章的练习全部做完、确认无误时,每次都要走完这套收尾流程(别遗漏、别偷懒):

1. 跑一遍验证:node js_notes/NN-topic.js 确认整章(含用户练习答案)能跑、 输出符合预期;必要时 node --check 先查语法。
2. 留学习痕迹:用户练习中犯过的错,按"改用户代码时留学习痕迹"那条,在文件里 保留 ❌/✅ 对照(绝不留能跑的坏代码)。
3. 吸收错误:本章冒出的、有教益的新错误,按上面规则并入 my-mistakes.md (值当就新开条目、不值当就在相关条目补一句;纯手误/已覆盖的不记)。
4. 更新进度:勾选 js_notes/README.md 里该章的进度框([ ] → [x]), 必要时补上本章实际覆盖到的关键词。
5. 提交:按逻辑拆成干净的 commit 提交(Angular 风格 message);工作区留干净。
6. 导向下一步:简述下一章要学什么、和已学内容/pi 目标的关联,让用户决定是否继续。

改用户代码时留下学习痕迹(用户的长期要求)

每当用户让你改他的代码或加标记时,把错误版本作为注释掉的 ❌ / ✅ 对照 保留在修复的旁边 —— 好让未来的他看到错在哪、为什么错,而不仅仅是改对后的 那一行。这与用户已经在 06-arrays.js / 07-objects.js 里用的风格一致:

// ❌ splice 返回的是"被删除的元素",不是修改后的数组
// console.log(q.splice(1, 0, 'second'))
// ✅
q.splice(1, 0, 'second')
console.log(q)

这类痕迹的规则:

• 把错误行注释掉(绝不留下能跑的坏代码),放在修复的上方。
• 一行简短的 // ❌ 原因 说明为什么错;// ✅ 标出正确的代码。
• 这适用于演示/教学区块,以及用户明确要求的修复 —— 它不推翻"绝不写答案":对于用户还没动手的 轮到你 练习,仍然不要 往里丢解答。
• 由此浮现出的、有分量的新陷阱,通常也应加一条 my-mistakes.md 条目 (以上文"只记有教益的"这条为准)。

讲清为什么,而不只是规则(用户的长期要求)

比起干巴巴的"就是这么规定的",用户从底层机制里学得快得多。只给规则、 不给原因的简略笔记是不够的 —— 用户明确指出 // 带 {} 就得自己写 return 太晦涩。当一条规则有其原因时,先讲原因;机制一旦讲清,规则就不言自明 (而且往往好几条规则会归结到同一个原因)。

举例说明 —— 箭头函数的函数体与 return。先说出那句最核心的话,再让 一切作为它的推论自然而然地推出(能找到那句核心才是本事 —— 用户曾修正过一版 从 { 的两种身份出发、而非从那句核心出发的草稿):

• 核心一句:=> 的右侧期待一个表达式(某个求值后得到一个值的东西)。
• 给它一个表达式 → 那就是那个值 → JS 把它返回(隐式返回)。 在那里写 return 是非法的:return 是语句,不是表达式,所以 (a, b) => return a + b 会 SyntaxError。
• { ... } 是逃生舱:以 { 开头的函数体会让 JS 把它当作语句块, 语句块不产生值 → 你必须显式 return,否则得到 undefined。
• 由这同一句核心推出:对象字面量也以 { 开头,于是和语句块规则冲突 → 用括号包起来以强制进入表达式上下文:(x) => ({ name: x })。

由此得出的实操习惯:

• 优先说"X 因为解析器/引擎看到了 Y",而不是"总是这样做 X"。
• 用运行代码来验证,当它能让论点更锋利时 —— 用户看重看到真实的报错 信息或输出,胜过一句断言(例如用 node --check 显示一个真实的 SyntaxError)。

讲解【直接写进文件】,别只留在聊天里(用户的长期要求)⭐

用户反馈:讲解如果只写在聊天回复里,事后几乎不会再翻出来;而临时验证文件 (/tmp/*.js)他更是看不到。所以成品是文件,不是聊天。当一段讲解值得 留存时:

• 直接写进对应的 NN-topic.js(概念区讲原理、示范区放可跑代码), 而不是"先在聊天里长篇讲一遍、再写一遍文件" —— 那样既浪费上下文,产物 用户又拿不到。聊天里只做极简导读 + 指向文件哪一节。
• 临时用 /tmp/*.js 跑验证没问题,但结论要落进文件;别把只存在于 /tmp 或聊天里的解释当成交付。
• 跨主题的点,写进该去的那一章,并在相关章节挂一句呼应(例:提升 hoisting 写进 10-functions.js,在 02-variables.js 的 var 那格挂一句指过去)。
• 这条和上面"讲清为什么""留 ❌/✅ 痕迹"是一套:原理讲清 + 落进文件 + 可追溯,才是一次完整的讲解。

运行代码

这里没有构建系统、没有 package.json、没有 linter、没有测试套件 —— 这是一个学习仓库,不是一个应用。代码逐个文件运行:

node js_notes/06-arrays.js       # 运行单个主题文件
node --check js_notes/09-loops.js  # 只做语法检查,不执行

在编辑器里,用户也会用 Quokka.js(内联显示实时 console.log 值;免费版 —— 不支持 //? 实时注释)或 Code Runner(▷ 按钮)来运行文件。

自足文件 vs 浏览器文件: 一个 .js 文件如果自己定义了它用到的一切、 且不碰 document,就能在 Node/Quokka/Code Runner 下运行。而依赖另一个脚本里 变量的文件,或使用 document/DOM 的文件(第 21 天以后以及那些小项目), 必须通过它们的 index.html 在浏览器里打开、配合 F12 控制台 —— 在 Node 下 运行会抛错(例如 firstName is not defined、document is not defined)。

内容语言

散文、笔记、讲解用中文;代码、标识符、commit message 用英文。 Commit message 遵循 Angular 风格(<type>(scope): description)。

Git 远端

这个克隆是从原课程 fork 出来的:

• origin → github.com/JaydonZhao/30-Days-Of-JavaScript(用户的 fork;推到这里)
• upstream → github.com/Asabeneh/30-Days-Of-JavaScript(原作者;拉取教程更新用 git fetch upstream && git merge upstream/master —— 用 merge,不用 rebase)

工作直接发生在 master 上(这个 fork 的 master 独立于 upstream 的,所以 用户的提交永远不会碰到别人的仓库)。这个 fork 是公开的 —— 不要提交任何 私密内容。