inBuilder 低代码平台开发者分享课丨变量命名要义
引言
各位同学，大家好。或许你现在在使用浪潮海岳低代码平台 inBuilder 进行开发，又或者是传统的开发方式。
但不论你使用哪种开发方式和开发语言，从事什么样的业务，我们每天都面临着对大量的变量进行命名的场景。 同时，软件工程是一个复杂度极高的工程，软件开发需要多人协作并长期维护。
在这个大背景下，我们要写出优秀的代码，要求很强的逻辑性、很高的可读性和扩展能力，需要我们重视命名这项工作。此处的命名包含变量命名、类命名、包命名、文件命名、路由命名等。很多同学写代码，或因经验不足、或因项目急，或因词汇量不够，在变量命名时大脑一片空白，好一点的会用些词不达意的简单单词，实在想不出来就用拼音代替。可谓八仙过海，各显神通。这篇文章，旨在帮助同学更好更快地命名变量。主要讲下什么是一个好的变量命名，优秀的变量命名是如何想出来的，以及列出命名变量时常用的单词词汇。
最佳的变量名
在命名变量时，最重要的考虑因素是，变量名要完整且准确地描述变量所代表的实体。换句话说，通常情况下，对于变量实体的描述就是对该变量最好的命名。例如 complexcityOfPassword，unSavedRecords，healthIndicator，tasksToExecute，teamNumCount
变量命名的几种常见类型
数据
可以用 XXXList、XXXMap、XXXSet 来表示，例如 menuList、fieldList、referenceMap
也可以用集合表示的事物的复数形式，XXXs，XXXes，例如：rows、cols、users、details、items
特殊状态
开发中经常遇到需要处理的数据，比方需要进行过滤挑选的数据、选中的数据、未保存的数据、当前数据，这类变量必须在前面加上修饰词、限定词。例如：filteredDetails、selectedRows、unSavedRecords、currentIndex、totalCount、defaultPassword、commonTarget、expiredKeys
标志性变量
这类变量通常是布尔变量，只有 true 和 false。表示是否可以用 isXXX，flag 例如：isLogin、isLast；表示开关可以用 enable、switchOn、；表示成功失败，可以用 succeed、found。尽量不要使用否定形式，例如：notXXX，disable，failed，否定形式容易让人难以理解。
带层级关系变量
这种变量在处理嵌套数据的时候最常见，可以使用表示层级关系的形容词修饰。
例如：outerContainer、nestedException、innerPage、wrapedData、includedFiles、coveredDetail、parentObj、enclosedArea
特定范围
范围类的形容词包含时间、地点、位置等几大类。
时间有现在、过去、未来，例如：lastestOperation、
地点有国内、国外、当地、远程，例如：localMachine、remoteClient、
位置有上下左右前后，例如：currentItem，leftSide，topPanel
对象属性
对于对象的属性名，最好加上对象本身的名字，用 xxxProperty 表示，例如：userInfo、objId、tabName、requestData、sysOption、tokenTime
另一种表示形式是把属性名放在对象名之前，用 xxxOfXxx，例如 lengthOfSubstr、complexcityOfPassword、fieldsOfObj
交互型变量
系统间交互、方法间调用都可以用下面这种形式来体现交互性。例如：responseForPos、tasksToExecute
角色型变量
这种变量最能体现面向对象编程。面向对象编程，通俗来讲就是各司其职，每个对象都有自己的专属工作。
这种变量形如事物+动作的执行者。
例如：eventHandler、dataConverter、loadBalancer、messageGenerator、requestDispatcher、healthIndicator、ConfigurationImportSelector、cacheLoader、
描述型变量
这种变量后面通常会添加一个体现该变量作用的类名。(这种方式在给类起名字时最常用、Java 类名首字母要大写)
例如：userEntity、serviceInstance、orgQueryService、redisConfig、netConstant
临时变量
有些临时变量，不必大费周章。当你在小的 for 循环中、嵌套的 for 循环中需要给对象的属性命名时，不要给它加上限定词。例如下面的代码，for 循环的 i 不需要 currentIndex 这种，写了反而看着很累。 在 Java 等很多语言中，i、j、k 都约定为 index。
let objs = [];
for (let i = 0; i < idList.length; i++) {
let item = that.vm.getObjById(idList[i]); objs.push(item);
}
return objs;
变量命名的约定/习俗（Convention）
各行各业，都有自己行业内约定成俗的做法，软件工程也不例外。 同时，软件工程是基于电子计算机、互联网等大背景下，也要考虑大背景下的约定。 另外，软件工程可以应用到传统的各行各业，也必须要遵守各行业的约定。 在这里，我们引出一个概念，叫做领域（Domain）。一切编码一定要遵守领域内的约定。
领域
互联网是一个领域，在此领域下，有像 DNS、IP、HTTP 等这样常见的名称，因此你不能将这些符号来尝试用在你自己创造的实体上。inBuilder 也是一个领域，在此领域下，有像 MSU、CAF、BizContext 等名称，你也不能用它来表示其他含义。权限控制，也是一个领域，在此领域下，有用户、角色、权限等概念，你最好也不要使用其他词汇来表示这三者，独树一帜，要使用项目上约定成俗的词汇。特别是算法一类的领域，比如加密算法，在此领域下有各种私钥、公钥、偏移量等概念，不要试图让很多约定成俗的简写，变成非专业人士就能看懂的词汇，这样的做法，破坏了领域内的共同认知。领域其实也可以分成业务领域和技术领域。尽量避免把技术词语用在具体业务中，把技术领域专业的词放到业务领域，会很不协调。反之亦然。 例如，classLoader、eventHandler 等基础架构层的东西放到财务模块，就显得很不协调。而正确的做法应该是封装，对外暴露接口，屏蔽掉具体细节。这种不协调的做法在实际开发中还是蛮常见的，需要多多注意。
Java 编码的约定
i,j 通常为索引变量。
常量要大写，使用下划线来分割。
类和接口名称要首字母大写，采用驼峰命名。
变量和方法名要字母小写，采用驼峰命名。
get 和 set 前缀用在访问变量的方法名上。
约定的好处
约定的最大好处就是减少开发成本。 体现在以下几点：
通过项目来传递知识。接手陌生的项目时，一个单词在项目中频繁出现，这个单词一定是非常重要且基础的概念，你可以快速了解到这些概念之间的联系，从而构建新的知识网络。
快速开发。阅读源码，你可以得到约定成俗的一套词汇表，在你继续开发的过程中，你可以大胆放心地使用这些词汇，而不会担心会有别人不理解你的代码。也不需要绞尽脑汁，浪费时间地去想一些相关的单词。
消除歧义。同一个概念，很容易被翻译成两三个单词，这就造成了巨大的学习成本。看了半天源码，发现两个单词代表的是同一类实体。
命名时的检查列表
在命名时，可以通过检查一下几个问题来确定，自己的命名是否是一个好的命名。
能不能准确且完整的表意
能否更加精简或使用简写
是否具有误导性、有歧义
是否使用了数字（建议不要使用数字）
是否容易拼错、是否生僻字
是否易读
能够使用布尔变量替代，布尔变量能够清晰的表达是或否
有没有遵守约定、是否参照了项目中的其他命名
变量单词词汇
下面列出了我整理的部分常见变量单词词汇的截图，想要查看更多，点击图片下方的词汇表地址。
神器：变量命名网站 CODELF
给大家介绍一款自动生成变量名的神奇网站 CODELF，只要输入相关词语，就能生成大量的相关变量名，试试吧。 CODELF
附录
类命名
类的命名与变量命名的区别很大，我们都知道，类是面向对象语言才有的概念。
也正是因为如此，类的命名要比变量命名要正式的多。
第一要义就是面向对象，适度抽象。
所谓面向对象，就是要确定此类的指责，负责的内容是什么。因此，我们可以给它命名为：HibernateResourceResolver、SerializerFactory、ZipHelper。让人一看，就知道这个类是来干什么的，可能包含有哪些 API。
若想了解更多关于 inBuilder 的更多相关内容，可点击下述地址下载安装浪潮海岳低代码平台 inBuilder 开源社区版
还未添加个人签名 2023-03-07 加入
塑造企业一体化研发新范式
评论