From e80c944c404afd387535c236a054da93872b7d5a Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 22 Oct 2026 13:14:03 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20=E5=87=BD=E6=95=B0=E7=9A=84?= =?UTF-8?q?=E6=B0=B4=E5=9C=9F=E4=B8=8D=E6=9C=8D=E4=B8=8E=E3=80=8C=E5=91=BD?= =?UTF-8?q?=E5=90=8D/=E4=BB=A3=E5=85=A5=E3=80=8D=E9=87=8D=E6=9E=84=20?= =?UTF-8?q?=E2=80=94=20=E8=AE=BE=E8=AE=A1=E5=93=B2=E5=AD=A6=E5=B1=82?= =?UTF-8?q?=EF=BC=88=E5=90=AB=201322=20=E5=87=BD=E6=95=B0=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E5=88=86=E7=B1=BB=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 命题(来自用户):函数是预先抽象,自然语言是即席描述;正常人不会说「要算 37 的两倍 得先抽象一个函数」,而是直接说乘二。故函数在代码即文档里错位。 本文只谈语义表示与自然语言映射,不谈编译器与语法糖。 一、量化证据:Marqdo 的 ## 其实不是「过程」 1322 个函数: - 纯返回式(零可执行语句,只有一个返回表达式)765(57.9%) - 一行式 935(70.7%);可执行语句数中位数 0、平均 2.2 - 较长(≥10 行)仅 62(4.7%) 按语义功能分类: - 纯命名式 754(57.0%)→ 对应「所谓 X,是指…」 - 条款式(有分支无副作用)103(7.8%)→ 对应「凡…则…」 - 遍历式 26(2.0%)、命令式(含 print)83(6.3%)、线性计算 356(26.9%) 结论:命名+条款 = 64.8%,真实副作用只有 6.3%。 即三分之二的 ## 落在「定义/条款」两种自然语言形态里,不需要过程语义。 二、复用经济学:为什么文档里抽象格外别扭 成本 = 定义 + 读者的跳转 + 维护;收益 = N 次复用省下的重复。 抽象值得做 ⟺ 复用次数×复杂度 > 定义成本 + N×跳转成本。 代码里 N 大、跳转便宜;文档里 N 常为 1、跳转昂贵(读者被打断)。 → 大量文档中的「函数」是负收益:只用一次却强迫回头查定义。 这正是「正常人不会这么说话」的形式化解释:说话默认对方不知道你的定义,倾向就地展开。 三、自然语言复用的六种形态(程序语言只承认一种) 重复 / 指称(该金额)/ 命名(所谓 X)/ 条款(凡…则…)/ 范例(以 37 为例)/ 表格。 命名只是六分之一,却被程序语言变成唯一入口。 四、三个语义立场 甲 定义—代入:一段正文被命名,使用=按角色代入后重述。覆盖 58% 现状,与 ## 结构一致。 乙 条款—援引:条件→结论,援引条款给出适用事实。最贴中文说明文,1./2./3. 已有。 丙 配方—配料:用料表+做法,参数=配料行。最可读但表达力最弱、无法组合。 → 推荐甲为主、乙为辅;丙作为甲的呈现(契约表)。 五、代入 vs 调用(为什么代入更贴人话) 心理动作、输入意义(一套名字 vs 两套)、结果意义、可嵌入叙述、一次性使用可取消。 关键:抽象必须能被「取消」——就地描述与命名代入是同一切换,提升/展开是编辑动作而非必经入口。 六、落到已有载体:只缺一环 命名(#/##)、正文(叙述+标记)、未定的量(体推断)、结论(*…*)、条款(1./2./3.)、 配料表(GFM+契约表)全部已有。**唯一缺的是「具名给值」**——问题因此缩小。 七、硬边界:自然性 vs 可判定性 角色具名(可判定,略啰嗦)/ 位置(实测叙述顺序一变绑定就翻转)/ 语境隐式(130 个形参名撞车,不可判定)。 → 只有「具名」同时可读且可判定。也解释了为何叙述式动词不可取:把判定交给未标记的词。 八、三个未决哲学难题:副作用(6.3% 需保留命令语义)、递归(代入=有限展开)、定义时序(能否前向引用)。 未改代码。附四项待裁决(含是否接受「不支持递归」、具名给值的最小形态)。 --- doc/design/function-as-naming-philosophy.md | 304 ++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 doc/design/function-as-naming-philosophy.md diff --git a/doc/design/function-as-naming-philosophy.md b/doc/design/function-as-naming-philosophy.md new file mode 100644 index 0000000..379070d --- /dev/null +++ b/doc/design/function-as-naming-philosophy.md @@ -0,0 +1,304 @@ +# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代 + +| | | +|---|---| +| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) | +| 日期 | 2026-10-22 | +| 命题来源 | 用户:「函数是复用、是对高度凝练内容的提炼加工;正常人不会说『计算 37 的两倍需要抽象一个函数』,而是直接说乘二」 | +| 定位 | 本文只谈**语义表示**与**自然语言映射**,不谈编译器与语法糖 | + +--- + +## 0. 把你的观察写成三条命题 + +**命题一(现象)**:函数是一种**预先抽象**装置——必须在使用之前先把内容提炼并命名,还要声明它需要哪些输入。 + +**命题二(对照)**:自然语言是**即席描述**——先把事说清楚,只有在内容确实要反复出现时,才顺手给它一个名字("以上做法,我们称为…"),而且命名之后它可以像普通名词/动词一样被使用。 + +**命题三(结论)**:因此「函数」这套仪式与「代码即文档」错位。要解决的不是调用写法,而是**用什么语义表示来承担"复用"这件事**。 + +本文的答案先给出来: + +> **Marqdo 需要的不是更好的"函数",而是把「函数」还原成「命名」,把「调用」还原成「代入」。** +> 函数 = **一段被命名的正文**;参数 = **那段正文里尚未确定的量**;调用 = **把这些量代入后重述一遍**。 + +--- + +## 1. 语料给出的证据:Marqdo 的 `##` 其实不是"过程" + +统计 `lib/ ext/ examples/ tests/` 全部 1322 个 `##`: + +| 指标 | 数值 | +|------|------| +| 函数总数 | 1322 | +| **纯返回式**(零可执行语句,只有一个返回表达式) | **765(57.9%)** | +| 一行式(可执行行 ≤1 且返回 ≤1) | 935(70.7%) | +| 极短(可执行行 ≤2) | 1162(87.9%) | +| 较长(可执行行 ≥10) | 62(4.7%) | +| 可执行语句数**中位数** | **0** | +| 平均 | 2.2 | + +典型代表:`## str_trim`、`## contains`、`## to_upper`——**一个名字包一个表达式**。 + +这说明:**人们用 `##` 在做"命名",语法却要求他们按"过程抽象"的仪式来做。** +签名(`+ n`)、祈使式调用(`> f 1 2`)、返回值约定(`*…*`)全是过程语言的行头, +而实际内容是"给这个式子起个名字"。 + +**水土不服不是感受,是可以量化的形式错配。** + +### 1.1 按「语义功能」再分一次类 + +把 1322 个函数按内容形态归类(同一函数可能重叠,故按主特征优先): + +| 形态 | 判据 | 数量 | 占比 | 自然语言对应 | +|------|------|------|------|-------------| +| **纯命名式** | 零语句、零副作用、零分支、零循环,只有一个返回式 | **754** | **57.0%** | 「所谓 X,是指…」 | +| **条款式** | 有分支、无副作用 | 103 | 7.8% | 「凡…则…」 | +| **遍历式** | 有循环、无副作用 | 26 | 2.0% | 「对每一项…」 | +| **命令式** | 含 `print` 等副作用 | **83** | **6.3%** | 「打印…」祈使句 | +| 线性计算(其余) | 有语句但无控制流/副作用 | 356 | 26.9% | 「先…再…」 | + +两个结论: + +1. **命名 + 条款 = 64.8%** —— 三分之二的 `##` 落在"定义"与"条款"两种自然语言形态里, + 而这两种恰好不需要"过程"语义(§4 立场甲、乙)。 +2. **真正的副作用只有 6.3%** —— 也就是说"命令/祈使"语义只是少数派, + 完全可以隔离成一小块(§8.1),不必让它污染整体读法。 + +--- + +## 2. 为什么"抽象"在文档里格外别扭:复用经济学 + +抽象不是免费的。它有三项成本: + +| 成本 | 内容 | +|------|------| +| **定义成本** | 要写一次定义(名字、输入、边界) | +| **跳转成本** | 读者看到名字,必须回到定义处才能理解(文档尤其致命:要翻页/滚动) | +| **维护成本** | 定义改了,所有使用处语义随之变化 | + +收益只有一项:**同一内容被复用 N 次时省下的重复**。 + +于是有: + +> **抽象值得做 ⟺ 复用次数 × 内容复杂度 > 定义成本 + N × 跳转成本** + +在**代码**里,N 往往很大、跳转成本低(IDE 跳转、同屏),所以抽象划算。 +在**文档**里,N 常常是 **1**,跳转成本高(读者在阅读流里被打断),于是: + +> **文档中大量"函数"是负收益的**——它们只被用一次,却强迫读者回头查定义。 + +这解释了为什么你会有"正常人不会这么说话"的直觉:**说话的默认假设是对方不知道你的定义**, +所以人话倾向于**就地展开**;而函数默认假设读者愿意跳转。 + +--- + +## 3. 自然语言里「复用」到底有几种形态 + +程序语言只承认其中一种(命名+参数化),这是错配的第二层。 + +| 形态 | 自然语言的样子 | 对应的程序装置 | Marqdo 现状 | +|------|---------------|---------------|------------| +| **重复** | 再说一遍 | 复制粘贴 | ✅ 允许 | +| **指称** | 如上所述 / 同前 / 该金额 | 变量、引用 | ✅ `` `名` `` | +| **命名** | 所谓 X,是指…;以下称 X | 定义 / 函数 | ✅ `## X` | +| **条款** | 凡…则…;若…应… | 条件分支、规则 | ✅ `1. 2. 3.` | +| **范例** | 以 37 为例 | 样例/测试 | ⚠️ 仅测试目录 | +| **表格/清单** | 见下表;用料如下 | 数据、查表 | ✅ 表格 | + +**关键发现**:命名只是六分之一,但程序语言把它变成了**唯一的复用入口**。 +而文档写作里,**指称("该金额")与条款("凡…则…")比命名更常用**。 + +--- + +## 4. 三种候选语义表示(哲学立场) + +要"代替水土不服",必须给出**语义模型**,而不只是换个写法。三个候选: + +### 立场甲:定义—代入(Definition & Substitution) + +**语义**:一段正文被命名 → 成为一个**定义**。使用它 = 把定义里的自由量按**角色**代入,再重述。 + +```markdown +## 加倍 + +把 `x` 乘以二,得 *y* +``` + +使用(语义读法):**按「加倍」代入 x=37,得 74。** + +| 维度 | 评价 | +|------|------| +| 自然语言对应 | ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力 | +| 与 Marqdo 契合 | ✅ `##`/`#` 本来就是标题(文档结构),天然是"定义"的载体 | +| 参数观 | ✅ 角色(具名),不是位置占位符 | +| 复用单位 | ✅ **文本段落本身**(文档即单位,符合"代码即文档") | +| 71% 的现有一行式函数 | ✅ 直接就是"命名的表达式",无需过程仪式 | +| 缺点 | 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5) | + +### 立场乙:条款—援引(Clause & Citation) + +**语义**:条件 → 结论。使用 = 援引条款并给出适用的事实。 + +```markdown +## 计费规则 + +若 `里程` 超过 100 公里,则 `费用` 按 8 折计。 +``` +使用(语义读法):**本单里程 120 公里,依「计费规则」,费用按 8 折。** + +| 维度 | 评价 | +|------|------| +| 自然语言对应 | ✅✅ 「凡…则…」是中文说明文/法条/规章的骨架 | +| 与 Marqdo 契合 | ✅ `1. 2. 3.` 分支已经就是条款形式 | +| 缺点 | 数值计算写成条款别扭("把 37 乘以二"不是条款) | + +### 立场丙:配方—配料(Recipe & Ingredients) + +**语义**:一张用料表 + 一段做法。参数 = 配料表中的行。 + +| 维度 | 评价 | +|------|------| +| 自然语言对应 | ✅ 菜谱、工艺卡、表单 | +| 与 Marqdo 契合 | ✅✅ 表格优先正是 Marqdo 的特色;契约表已是雏形 | +| 缺点 | 表达力弱;无法递归、无法组合;"给值"变成填表 | + +### 取舍 + +| | 甲 代入 | 乙 条款 | 丙 配料 | +|---|---|---|---| +| 覆盖"命名表达式"(58% 的现状) | ✅✅ | ⚠️ | ❌ | +| 覆盖"条件规则" | ⚠️ | ✅✅ | ❌ | +| 覆盖"数值流程" | ✅ | ❌ | ⚠️ | +| 可读性 | 高 | 最高 | 最高(但最弱) | +| 与 `##` 结构一致 | ✅ | ✅ | ⚠️ 表为主 | + +**推荐:以甲为主,乙作为甲内部的一种段落形态。** 理由见 §6。 + +--- + +## 5. 「代入」为什么比「调用」更贴自然语言 + +这不是文字游戏,三处实质差异: + +| 维度 | 调用(invocation) | 代入(substitution) | +|------|-------------------|---------------------| +| 读者的心理动作 | "跳过去,看它做什么,再回来" | "把这个式子代进去" | +| 输入的意义 | 实参 → 形参(两套名字) | 角色 → 定义里的同一个名字(**一套名字**) | +| 结果的意义 | 函数返回了一个值 | 式子变成了具体结果 | +| 出现位置 | 必须是独立语句或表达式 | 可以**嵌在叙述里**("加倍后为 74 件") | +| 一次性使用 | 仍要付出定义+跳转成本 | 可以**不定义,直接展开**(§5.1) | + +### 5.1 关键:抽象要能被"取消" + +自然语言的强大在于**可省略**:能一句话说清就不起名字。 +所以语义模型必须允许同一件事有**两种粒度**,并可以随时在两者之间移动: + +| 粒度 | 写法(示意) | 何时用 | +|------|-------------|--------| +| **就地描述** | 把 37 乘以二,得 74 | 只用一次 | +| **命名后代入** | 按「加倍」代入 x=37,得 74 | 复用多次 | + +而且**提升与展开都是作者的编辑动作,不是必须的入口**。 +这正是"抽象可选"——今天的函数是"必须先抽象",这是错配的第三层。 + +### 5.2 与 58% 纯表达式函数的对应 + +`## to_upper` 这类函数,用"代入"读就是: + +> 「to_upper 的定义是:把 `s` 变成全大写。」使用:`to_upper` 代入 s="abc" 得 "ABC"。 + +它读起来是一个**定义 + 一次代入**,而不是"调用一个过程"。这与它的实际内容(一个表达式)一致。 + +--- + +## 6. 这套语义如何落到 Marqdo 已有的东西上 + +| 自然语言的成分 | Marqdo 已有载体 | 需不需要新东西 | +|---------------|----------------|---------------| +| 命名(给出定义) | `#` / `##` 标题 | ❌ 已有 | +| 正文(定义的内容) | 叙述 + 标记代码 | ❌ 已有 | +| 未确定的量(角色) | 体推断出来的形参(v0.3 已有) | ❌ 已有 | +| 角色的**具名给值** | (缺失) | ✅ **这是唯一真正缺的一环** | +| 结论(得…) | `*…*` 返回 | ❌ 已有 | +| 条款(凡…则…) | `1. 2. 3.` 分支 | ❌ 已有 | +| 配料表 | GFM 表格 + 契约表 | ❌ 已有 | +| 引用(依…) | (缺失) | ⚠️ 与"具名给值"是同一件事 | + +**结论:缺的只有一件事——「具名给值」的形式。** + +也就是说:语义模型(代入)几乎不用改,语法只缺一个"把角色填上"的最小约定。 +这把问题从"要不要重新设计函数"缩小到"这一个小约定怎么长得最不刺眼"。 + +--- + +## 7. 不可回避的哲学难题:自然性 vs 可判定性 + +自然语言判断"哪些量要代入"靠**语境**(前文、常识、指代)。 +编译器不能。所以必须有一条**显式约定**,无法省掉。 + +三种可能的约定形态(只列哲学性质,不列语法细节): + +| 形态 | 自然的程度 | 可判定的程度 | 风险 | +|------|-----------|-------------|------| +| **角色必须具名给出** | 中(像"按定义,其中 x=37") | ✅ 完全可判定 | 略啰嗦 | +| **靠语序(位置)** | 高 | ✅ 可判定 | ❌ 已实测:叙述顺序一变,绑定就翻转(见 call-syntax-from-marks.md §4.3) | +| **靠语境(隐式)** | 最高 | ❌ 不可判定 | ❌ 130 个形参名撞车 | + +**这是整件事的硬边界**:越像人话,越难判定。Marqdo 必须选"具名"这一档—— +它是**唯一同时可读且可判定**的点。 + +而这也解释了为什么"叙述式动词"(`执行`)不可取:它把判定交给了一个**未标记的词**, +既没有自然的程度优势,又破坏了"叙述安全"。 + +--- + +## 8. 三个尚未解决的哲学问题 + +这些是真问题,需要后续立场,不宜草率定: + +1. **副作用怎么办?** + "把 37 乘以二"是纯代入;"打印 74"呢?打印**改变世界**,不是代入。 + → 副作用可能必须停留在"命令"语义(今天的 `> print`), + 而这会让文档里同时存在"代入"与"命令"两套读法。这是否可接受? + +2. **递归与自引用怎么办?** + 代入是有限展开;递归是无限展开。若坚持代入选义,递归就不可表达。 + → 是否接受"Marqdo 不支持递归"?还是给递归单独一套"过程"语义? + +3. **定义的时序怎么办?** + 自然语言允许先使用后定义("如上,我们称之为…")。代入语义要求定义先存在。 + → 是否允许前向引用(读者先看到 `加倍`,后面才看到定义)? + +--- + +## 9. 一句话总结与建议 + +> **Marqdo 的问题不是"函数不好用",而是"函数是过程语言留给文档的遗产"。** +> 文档需要的不是过程,是**命名**;不是**调用**,是**代入**。 + +建议的语义立场(待你裁决): + +| 项 | 建议 | +|----|------| +| 复用单位 | **一段被命名的正文**(而非过程) | +| 参数观 | **正文中未确定的量**(角色,具名) | +| 调用观 | **代入**(可读作"按…代入…") | +| 抽象时机 | **可选提升**:默认就地展开,需要复用时才命名 | +| 唯一新增约定 | **具名给值**(形态待定,但必须具名,理由见 §7) | +| 保留"命令"语义 | 仅用于副作用(`print` 等),与"代入"分层 | +| 条款 | 作为定义的一种段落形态(`凡…则…`),不另设机制 | + +--- + +## 10. 待你裁决 + +1. **是否接受"函数→命名 / 调用→代入"这个总重构?** + 若接受,后续所有语法讨论都在这条轴上做取舍。 +2. **§8 的三个难题**你的倾向是什么(尤其"是否接受不支持递归")? +3. **"具名给值"的最小形态**:你更接受哪一种读感? + - `**加倍(x=37)**`(像函数调用) + - `按**加倍**,`x`=37`(像句子,但需要判定规则) + - 表格给出角色(像配料表) +4. 是否需要我把这份哲学立场,反向校验一遍**现有 1322 个函数**—— + 看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?