http://tommwq.tech/blog/2020/12/21/282
程序源代码、配置、脚本等任何可能发生变化的东西，都应当具备一定的自解释性。自解释性让这些东西更容易被理解，因而更容易被修改，同时降低了在修改过程中引入错误的概率。有人觉得，我可以查文档，可以上网搜索。但在实际工作中，文档常常不能及时更新，而且未必有足够的时间和权限上网搜索。自解释性就是要求程序代码、配置、脚本能够充分清晰的表明自己的业务意图、业务步骤、参数类型、参数值范围、约束、修改方法等信息。
对于程序代码，类和对象名字要反映出执行者（actor）在场景中角色，通常采用名词命名。方法名字要充分反映业务意图。通常可以采用动词或动词短语命名。如果参数过多，使用具有结构的对象封装参数，而不是将参数胡乱塞入Map<String,Object>传递。同时，方法要充分注释，写清楚参数和返回值的含义，可能抛出的异常和其他需要注意的地方。脚本也是一种程序源代码，因此可采用和程序代码同样的原则。
配置通常分为键值对格式（ini、properties）和结构化格式（JSON、XML）。配置项名字要清晰、无歧义。如果格式支持（比如XML、properties、ini），最好写清楚配置项的用途，数据类型，可以取值的范围、默认值等。如果配置中包含非ascii字符，最好在配置中写明使用的字符编码，以免出现乱码。
编写SQL时，DDL语句、自定义存储过程和函数、触发器等，也应当具备一定的自解释性。比如MySQL的CREATE TABLE语句支持COMMENTS，可以将列的用途写到COMMENTS里，将来使用SHOW CREATE TABLE就可以明白当初为何如此设计。
定义协议时，也要考虑自解释性。比如HTTP接口，充分利用GET/POST/PUT/DELETE语义。对于protobuf协议，使用枚举替代int，这样可以清楚的表明参数值的取值范围和意义。