编程中最难的就是命名？这几招教你快速上手

17611538698

webmaster@21cto.com

登录注册

编程中最难的就是命名？这几招教你快速上手

阿里巴巴中间件

编程语言 0 1372 2023-06-13 10:37:14

你可不能像给狗狗取名字那样给类、方法、变量命名。仅仅因为它很可爱或者听上去不错。

在写代码的时候，你要经常想着，那个最终维护你代码的人可能将是一个有暴力倾向的疯子，并且他还知道你住在哪里。

为什么命名很重要？

Aliware

在项目中，从项目的创建到方法的实现，每一步都以命名为起点，我们需要给变量、方法、参数、类命名，这些名字出现在代码的每个角落，随处可见，混乱或错误的命名不仅让我们对代码难以理解，更糟糕的是，会误导我们的思维，导致对代码的理解完全错误。如果整个项目始终贯穿着好的命名，就能给阅读者一个神清气爽的开始，也能给阅读者一个好的指引。

要知道，代码的阅读次数远远多于编写的次数。请确保你所取的名字更侧重于阅读方便而不是编写方便。

为什么很难正确命名？

Aliware

有人称编程中最难的事情就是命名。我同样深以为然，中国有句古话叫做万事开头难。抛开环境搭建，真正到了编码阶段第一件事就是命名，而最常见的一种情况，就是毫无目的、仅凭个人的喜好的去决定了一个名字。但因为没有想清楚目标和具体实施步骤，所以进行过程中往往会面临无数次的小重构甚至是推倒重来。

1、缺乏意愿

害怕在选择名字上花时间，对做好命名的意愿不足，随心所欲，甚至无视团队对命名的基本规范，觉得编译器能编译通过，代码能正常运行就成。

其实对发现的命名问题进行重构和推倒重来并不可怕，最可怕的是当下程序员不具备发现问题后肯回过头来纠偏的意愿。这终将演变成为一场灾难。

2、缺乏思考

没想清楚被命名的事物是什么，事物应该承担什么职责，是否会对其他人造成误解。

新手程序员总会花很多时间学习一门编程语言、代码语法、技术和工具。他们觉得如果掌握了这些东西，就能成为一个好程序员。然而事实并不是这样，事实上，编程不仅仅关乎掌握技能和工具，更重要的是在特定范畴内解决问题的能力，还有和其他程序员合作的能力。因此，能在代码中准确的表达自己的想法就变得异常重要，代码中最直观的表达方式是命名，其次是注释。

3、缺乏技巧

选一个好的名字真很难，你可能得有较高的描述能力和共同的文化背景。并且知晓一些常见且应该避免的命名问题。

如果最终还是没法找到合适的名字，还请添加准确的注释辅助他人理解，等想到合适的名字后再进行替换，不过往往能够通过注释（母语）描述清楚的事物，命名应该问题不大，问题大的是连注释都无法准确表达，那说明可能当前类、函数、变量承担的职责太多太杂。

如何正确的命名？

Aliware

这里不讨论具体语言的命名规则，原因是不同编程语言命名规则各不相同，甚至不同团队间相同语言的命名规则也有出入。这里主要从提高可读性出发，结合我所在的客户端团队日常开发情况，以Java作为演示语言，给一些关于命名的建议。

1、名副其实

无论是变量、方法、或者类，在看到他名称的时候应该以及答复了所有的大问题，它应该告诉你，它为什么会存在，他做什么事，应该怎么做。如果在看到名称时，还需要去查找注释来确认自己的理解，那就不算名副其实。而且在发现有更好的命名时，记得果断替换。

Case1：到底怎样算End?

代码示例：

public interface OnRequestListener {/** * 请求结束 只有成功点才认为是真正的结束 * @param ... */void onRequestEnd(....);/** * 请求开始 * @param ... */void onRequestStart(...);}

大脑活动：

onRequestEnd是请求的什么阶段？请求成功和失败任一情况都算 “end”吗？喔，原来注释有写：“只有成功点才认为是真正的结束”。

修改建议：

// 省略注释public interface OnRequestListener {  void onStart(....);  void onSuccess(....);  void onFailure(...);}


2、避免误导

在每种语言中都有内置的标识符,他们都有特定的含义，如果和他们没有关联就不要在命名中加上他们。

2.1 避免使用令人误解的名字

Case1：命错名的集合

代码示例：

private List dataSet;

大脑活动：

“dataSet” 在最初一定是为了元素去重选择了Set类型，肯定后来某一个历史时刻发现有bug被偷偷改成了List类型，但是变量名没变。

代码跟读：

跟踪提交记录，呃，在18年被刚定义时就是 List<***> dataSet;

修改建议：

private List dataList;或者private List sections;

Case2：不是View的View类

代码示例：

/** 作者+日期 */public class RItemOverlayView {}

/** 作者+日期 */public class NRItemOverlayView {}

大脑活动：

“N”是啥意思？类名只有一个N的字母差别，难道是新旧的差别，新的和旧的有什么区别呢？

类名以View结尾，嗯，应该是一个视图，可是，视图为啥不用继承视图基类的？

代码跟读：

喔，N确实代表“New”的意思，NRItemOverlayView被首页推荐使用，RItemOverlayView被购后推荐使用。

这个类主要核心工作是构建浮层视图(职责并不单一)，而类本身并不是一个真正的视图；

修改建议：

// 放在首页推荐场景的包下public class ItemOverlayViewCreator {}

// 放在购后推荐场景的包下public class ItemOverlayViewCreator {}

Case3：整形变量为啥要用is开头

代码示例：

private int isFirstEnter = 0;

大脑活动：

为什么“is”开头的变量却声明成整形？到底是要计数还是判断真假呢？

代码跟读：

isFirstEnter < 1 做第一次进入的逻辑

修改建议：

private boolean isFirstEnter = true;

Case4：开关作用反掉啦

代码示例：

....if (InfoFlowOrangeConfig.getBooleanValue(POST_DELAYED_HIDE_COVER_VIEW_ENABLE, true)) {    hideCoverImageView();} else {    delayedHideCoverImageView();}

大脑活动：

为什么开关名为“delay....”为“true”的时候，走的不是delay逻辑，那开关要怎么发？容我多看几遍，是不是最近没休息好所以看岔了。

代码跟读：

反复看了几遍，确实是开关命名和实际操作完全相反，开关名意为“延迟隐藏封面视图”，执行的却是“立即隐藏封面视图”。

修改建议：

....if (InfoFlowOrangeConfig.getBooleanValue(IMMEDIATELY_HIDE_COVER_VIEW_ENABLE, true)) {

hideCoverImageView();} else {    delayedHideCoverImageView();}

3、做有意义的区分

如果单纯只是为了区分两个名称不能一样，就使用就使用诸如数字，字母来做区分的话，那似乎是毫无意义的区分。

3.1 避免在名字中使用数字

case1: 来自包名的暴击

问题示例：

以下是首页客户端的工程目录节选，数字化的包名：recommend、recommend2、recommend3、recommend4

大脑活动：

2、3、4难道是因为首页历史包袱太沉重，推荐迭代的版本实在太多导致Old、New单词不够用所以用数字来代替新旧4个历史阶段的版本吗？

代码跟读：

recommend：推荐的公共工具和模块；
recommend2：收藏夹场景的推荐实现；
recommend3：首页场景的推荐实现；
recommend4：购后场景的推荐实现；

修改建议：

这里暂时只讨论如何把数字替换成有意义的命名

3.2 避免使用具有相似含义的名字

case1：同一个类下的“刷新7剑客”

代码示例：

大脑活动：

为什么一个Adapter类对外有七个刷新数据的接口？

"refreshData()" 和 “speedRefreshData()” 是什么区别？

“mainRefreshData()” + "refreshDeltaData()" =“mainRefreshDeltaData()” ？是一个拆分组合的关系吗？

我应该在何总场景下如何正确的使用refresh，我在哪，我在做什么？

代码跟读：

大部分refresh代码线上并不会被调用。阅读和调试下来，实际还在生效的方法只有一个：“gatewayRefreshData()”。

修改建议：

实际上这已经不是一个单纯优化命名可以解决的问题，无论叫的多具体，面对7个刷新接口都会懵圈。期望在方法声明期间，作者多体量后来的阅读者和维护者，及时的调整代码。

后来者可以从实际出发去假存真，做减法干掉其它无用的6个刷新方法保留一个刷新接口。

case2：4个数据源定义，该用谁呢

代码示例：

声明1：

public interface IR4UDataSource {     ....}

声明2：

public interface RecommendIDataSource {    ....}

声明3：

public interface IRecommendDataResource {    ....}

声明4：

public class RecmdDataSource {    ....}

大脑活动：

4个推荐数据源，其中有3个是接口声明，为什么接口定义了不能多态，不能复用接口的声明？这三代的抽象好像有一丢丢失败。

代码跟读：

homepage 包下的 IR4UDataSource，和非常古老的首页曾经爱过，线上实际不会使用；

Recommend2 包下的“RecommendIDataSource” 属于收藏夹，但也属于古老版本，收藏夹不在使用；

Recommend3 包下的“IRecommendDataResource” 确实是首页场景推荐使用，但也是曾经的旧爱；

原来当今的真命天子是Recommend3包下的“RecmdDataSource”，一个使用俏皮缩写未继承接口的实体类，看来是已经放弃伪装。

修改建议：

......

3.3 避免使用具有不同含义但却有相似名字的变量

case1 : 大家都是view，到底谁是谁

代码示例：

public void showOverlay(@NonNull View view ...) {    ...     View rootView = getRootView(view);    DxOverlayViewWidget dView = createDxOverlayViewWidget();    dView.showOverLayer(view.getContext(), (ViewGroup)rootView, cardData, itemData);

  ... }

代码跟读：

代码中存在3个以view结尾的局部变量，rootView、view 、 dView，其中 view 和 dView 之间只有一个字母的差异，方法如果长一点，view 和 dView 使用频率在高一点，掺杂着rootView会让人抓狂。另外dView也并不是一个view，实际是个DXViewWidget。

修改建议：

public void showOverlay(@NonNull View hostView ...) {    ...     ViewGroup parentView = getParentView(hostView);    DxOverlayViewWidget dxOverlayViewWidget = createDxOverlayViewWidget();    dxOverlayViewWidget.showOverLayer(hostView.getContext(), parentView, ...);  ...}

4.使用读的出来的名称

使用读的出来的名称，而不是自造词，这会给你无论是记忆，还是讨论需要说明是哪个方法时，都能带来便利。可以使用达成共识的缩写，避免造成阅读障碍。

4.1 避免使用令人费解的缩写

Case1：接口定义中的俏皮缩写

代码示例：

/** * Created by *** on 16/8/6. */public interface IR4UDataSource {  ....}

大脑活动：

R4U是什么？R4和Recommend4这个目录有什么关系，难道是购后推荐的数据源定义吗？那U又代表什么？

代码跟读：

原来R4U是Recommend For You的俏皮写法

修改建议：

public interface IRecommendForYouDataSource {  ....}

Case2：成员变量命名的缩写

代码示例：

....// 标题指示器（indicators）private LinearLayout mTabLL;private TabLayout mTabLayout;....

大脑活动：

“mTabLL”是什么呢？有注释！难道mTabLL是指示器视图？“LL“”也不像是indicators的缩写，喔，LL是LinearLayout的首字母缩写。嗯，使用LinearLayout自定义做成指示器有点厉害！诶，不对，好像TabLayout更像是个选项卡式指示器的样子。

代码跟读：

原来“mTabLL” 下面声明的 “mTabLayout”才是指示器视图，“mTabLL”只是指示器视图的父视图。还好“mTabLayout”没有缩写成“mTabL”，导致和“mTabLL”傻傻分不清，作者已然是手下留情了。

修改建议：

....private LinearLayout mTabLayoutParentView;private TabLayout mTabLayout;....

Case3：局部变量命名的缩写

代码示例：

....for (PageParams.GroupBuckets ss:params.groupBucketIds.values()) {
if (ss != null) {        bucketIds.removeAll(ss.bucketIdsAll);        Collections.addAll(bucketIds, ss.currentBucketIds);    }}....

大脑活动：

"ss"是什么鬼，是不是写错了，GroupBuckets首字母缩写是“gb”，PageParams和GroupBuckets 的首字母缩写是“pg”

这难道是，PageParams 和 GroupBuckets 的尾字母缩写，在一个圈复杂度为18的方法中看到尾字母缩写“ss”？啊！好难受。

修改建议：

for (PageParams.GroupBuckets groupBuckets :params.groupBucketIds.values()) {    if (groupBuckets != null) {        ....    }}

5、使用可搜索的名称

若变量或常量可能在代码中多处使用，则应赋其以便于搜索的名称。

5.1 给魔法值赐名

Case1：数字魔法值没法搜索也看不懂

代码示例：

public static void updateImmersiveStatusBar(Context context) {  ....    if (TextUtils.equals(isFestivalOn, "1")) {        if (TextUtils.equals(navStyle, "0") || TextUtils.equals(navStyle, "1")) {            ....        } else if (TextUtils.equals(navStyle, "2")) {            ....        }    }  ....}

大脑活动：

对于TextUtils.equals(isFestivalOn, "1") ，我还能猜测一下这里的“1” 代表开关为开的意思。

那TextUtils.equals(navStyle, "0"/"1"/"2") 中的“0”，“1”，“2” 我该如何知道代表什么意思？

老板，请不要再问我为什么需求吞吐率不高，做需求慢了，可能是因为我的想象力不够。

修改建议：

实际上，协议约定时就不应该以 “0”，“1”，“2” 这类无意义的数字做区分声明。

public static final String FESTIVAL_ON = "1";public static final String NAV_STYLE_FESTIVAL = "0";public static final String NAV_STYLE_SKIN = "1";public static final String NAV_STYLE_DARK = "2";
public static void updateImmersiveStatusBar(Context context) {  ....    if (TextUtils.equals(isFestivalOn, FESTIVAL_ON)) {        if (TextUtils.equals(navStyle, NAV_STYLE_FESTIVAL)             || TextUtils.equals(navStyle, NAV_STYLE_SKIN)) {            ....        } else if (TextUtils.equals(navStyle, NAV_STYLE_DARK)) {            ....        }    }  ....}

5.2 避免在名字中拼错单词

Case1：接口拼错单词，实现类也被迫保持队形

代码示例：

public interface xxx {  ....  void destory();}

修改建议：

public interface xxx {  ....  void destroy();}

6、类的命名

应该总是名词在最后面，名词决定了这个类代表什么，前面的部分都是用于修饰这个名词；比如，假如现在你有一个服务，然后又是一个关于订单的服务，那就可以命名为OrderService，这样命名就是告诉我们这是一个服务，然后是一个订单服务；再比如 CancelOrderCommand，看到这个我们就知道这是一个Command，即命令，然后是什么命令呢？就是一个取消订单的命令，CancelOrder表示取消订单。

类的命名可以参考前面讲述过的规则。实际上往往了解一个类更多需要通过查看类的方法定义，而仅仅通过类名无法知晓类是如何工作的。关于类的更多内容，会在后续章节详细展开。

7、方法的命名

可以用一个较强的动词带目标的形式。一个方法往往是对某一目标进行操作，名字应该反映出这个操作过程是干什么的，而对某一目标进行操作则意味着我们应该使用动宾词组。比如：addOrder()。当方法有返回值的时候，方法应该用它所返回的值命名，比如currentPenColor()。

《代码大全》：变量名称的最佳长度是 9 到 15 个字母，方法往往比变量要复杂，因而其名字也要长些。有学者认为恰当的长度是 20 到 35 个字母。但是，一般来说 15 到 20 个字母可能更现实一些，不过有些名称可能有时要比它长。

7.1 避免对方法使用无意义或者模棱两可的动词

避免无意义或者模棱两可的动词。有些动词很灵活，可以有任何意义，比如 HandleCalculation()，processInput()等方法并没有告诉你它是作什么的。这些名字最多告诉你，它们正在进行一些与计算或输入等有关的处理。

所用的动词意义模糊是由于方法本身要做的工作太模糊。方法存在着功能不清的缺陷，其名字模糊只不过是个标志而已。如果是这种情况，最好的解决办法是重新构造这个方法，弄清它们的功能，从而使它们有一个清楚的、精确描述其功能的名字。

Case1: 名不副实的process

代码示例：

/** * 处理主图的数据 * * @return 如果有浮层数据就返回true，没有就返回false */private boolean processMainPic() {    ....    boolean hasMainPicFloat = false;  ....    return hasMainPicFloat;}
// 调用处boolean hasMainPicFloat = processMainPic();

大脑活动：

1、方法名的字面意思是处理主图（暂不纠结缩写Pic了），但是是如何处理主图的呢？

2、返回值是bool类型，是表示处理成功或失败吗？

3、查看注释解释，当前方法是在处理主图的数据，返回为是否存在浮层数据，为什么一个处理主图数据的方法检查的是浮层数据呢？

看完发现，这个方法原来是拿主图数据检查其中是否存在浮层数据，名不副实呀。

修改建议：

额外说明：既然工程默认“Float”是浮层，这里不做额外修改，但实际上不合理，毕竟Float在Java中表示浮点型数据类型，会引起误解。

/** * 是否有浮层数据 * * @return 如果有浮层数据就返回true，没有就返回false */private boolean hasFloatData($MainPictureData) {    ....    boolean hasFloatData = false;  ....    return hasFloatData;}
// 调用处boolean hasFloatData = hasFloatData(mainPictureData);

Case2: 我该如何正确使用这个方法

代码示例：

// 10多处调用... =  GatewayUtils.processTime(System.currentTimeMillis());
public class GatewayUtils {    ....    // 这个方法没有注释    public static long processTime(long time) {        return time + (SDKUtils.getTimeOffset() * 1000L);    }    ....}

大脑活动：

好多地方调用工具类的processTime，processTime到底是在处理些什么呢？

如果入参传入的不是 System.currentTimeMillis() 而是 SystemClock.uptimeMillis() 或者随意传入一个long值，方法的返回值会是什么呢？

修改建议：

public static long currentNetworkTime() {    return System.currentTimeMillis() + (SDKUtils.getTimeOffset() * 1000L);}

7.2 避免返回和方法名定义不一致的类型

Case1: 私有方法就可以乱定义吗？

码示例：

// 唯一调用处final IPageProvider pageProvider = checkActivityAvaliable();if (pageProvider == null) {  ....    return;}
// 函数声明private IPageProvider checkActivityAvaliable() {  IPageProvider pageProvider = pageProviderWeakReference.get();    if (pageProvider == null) {        PopFactory.destroyPopCenter(pageName);        return null;    }    return pageProvider;}

大脑活动：

check方法如果有返回值的话不应该是bool类型吗？

“Avaliable”拼错了诶，正确的单词拼写是：“Available”。

“IPageProvider” 和 “ActivityAvaliable” 是什么关系，为什么校验可用的Activity返回的是“IPageProvider”。

代码跟读：

原来方法里面偷偷做了一个销毁“PopCenter”的动作。把获取“PageProvider”和销毁“PopCenter”两件事情放在了一起。确实没看懂方法名和方法所做任何一件事情有什么关系。

修改建议：

干掉checkActivityAvaliable()方法。（这里不展开讨论高质量的函数相关内容）

final IPageProvider pageProvider = pageProviderWeakReference.get();if (pageProvider == null) {    PopFactory.destroyPopCenter(pageName);  ....    return;}