Files
marqdo/doc/design/function-as-naming-philosophy.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

15 KiB
Executable File
Raw Permalink Blame History

语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代

2026-10-23 审阅裁决:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以文档原生指导 §2–3的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。

状态 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)

语义:一段正文被命名 → 成为一个定义。使用它 = 把定义里的自由量按角色代入,再重述。

## 加倍

把 `x` 乘以二,得 *y*

使用(语义读法):按「加倍」代入 x=37,得 74。

维度 评价
自然语言对应 ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力
与 Marqdo 契合 ✅ ##/# 本来就是标题(文档结构),天然是"定义"的载体
参数观 ✅ 角色(具名),不是位置占位符
复用单位 ✅ 文本段落本身(文档即单位,符合"代码即文档")
71% 的现有一行式函数 ✅ 直接就是"命名的表达式",无需过程仪式
缺点 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5)

立场乙:条款—援引(Clause & Citation)

语义:条件 → 结论。使用 = 援引条款并给出适用的事实。

## 计费规则

若 `里程` 超过 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 个函数—— 看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?