动态类型语言如何命名变量、组织代码以提升可读性？

你提到的两种方案都不算长期维护场景下的最优解，各自有很明显的坑，行业内更通用的做法按优先级排序如下：

• 优先用语言生态原生的类型能力
  现在主流动态类型语言早就有成熟的静态类型补充方案：Ruby有内置的RBS类型签名，生态里还有Sorbet；Python3原生支持Type Hints；JavaScript直接用TypeScript就行。这类方案的好处是类型声明是标准化的，IDE能自动识别做补全、类型校验，一旦你改了代码没更新类型，工具直接报错，根本不会出现“注释和代码对不上、骗了读代码的人”的问题。
  比如Ruby里写了RBS签名，你根本不需要在变量名或者零散注释里提类型，任何人看签名就知道参数、返回值的精确类型，连哈希用符号键还是字符串键、数组里存的是什么类型都写得明明白白：

  def filter: (Hash[Symbol, untyped] result, Array[Symbol] allowed_keys) -> Hash[Symbol, untyped]
  

• 变量名讲语义，别硬加类型后缀
  类似result_hash、filters_array这种命名是早就过时的匈牙利命名法变种，搁二十年前IDE啥功能都没有的时候还有点用，现在鼠标往变量上一放就能看到类型，完全没必要把类型塞名字里。更麻烦的是后续优化代码的时候，比如你发现数组查键存在的性能太差，把filters从Array改成Set，难道还要把全项目里的filters_array都改成filters_set？纯纯给自己找活干。
  命名的核心是说清楚这个变量「是用来干嘛的」，不是「是什么类型」。比如你例子里的filters语义特别模糊，改成allowed_keys，别人扫一眼就知道这是存了所有允许保留的键的集合，比加个_array后缀清晰太多。
• 用标准化文档注释，别写零散的行内类型说明
  你写的# result: hash | filters: array (strings)这种随手写的行注释最大的问题是没有统一规范，写的人过俩月自己改了代码都记不住要更新注释，最后注释和实际逻辑对不上，比没注释还坑人。如果确实需要补充类型、使用约束，就用对应生态的标准化文档注释：Ruby用YARD，Python用主流的docstring规范，JavaScript用JSDoc。这类注释格式统一，IDE和文档生成工具都能识别，比随手写的行注释靠谱得多：

  # 从原始结果哈希中筛选出指定键对应的键值对
  # @param result [Hash{String => Object}] 待筛选的原始数据，使用字符串作为键
  # @param allowed_keys [Array<String>] 需要保留的键列表，元素为字符串
  # @return [Hash{String => Object}] 筛选后的结果
  def filter(result, allowed_keys)
    result.slice(*allowed_keys)
  end
  

• 轻量校验+单元测试做兜底
  核心的公共函数，可以在入口加只在开发/测试环境生效的类型校验，传错类型直接抛出明确的错误，读代码的人看到入口的校验逻辑，立刻就能知道参数的类型要求。另外给函数写几个覆盖核心场景的单元测试，测试用例本身就是最准确的使用说明——别人看测试里传的是字符串键的哈希、字符串组成的数组，立刻就知道该怎么传参，根本不会出现符号键、字符串键搞混的问题。

如果是写一次性跑的临时脚本、几百行以内的小工具，你想怎么写都行，自己看得懂就好；但如果是多人协作的长期项目，尽量用前面说的标准化方案，长期维护的成本会低非常多。

内容的提问来源于stack exchange，提问作者Dante