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

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

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

01 为什么命名很重要?

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

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

02 为什么很难正确命名?

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

1、缺乏意愿

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

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

2、缺乏思考

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

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

3、缺乏技巧

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

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

03 如何正确的命名?

这里不讨论具体语言的命名规则,原因是不同编程语言命名规则各不相同,甚至不同团队间相同语言的命名规则也有出入。这里主要从提高可读性出发,结合我所在的客户端团队日常开发情况,以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<SectionModel> dataSet;

大脑活动:

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

代码跟读:

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

修改建议:

private List<SectionModel> dataList;
或者
private List<SectionModel> 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中表示浮点型数据类型,会引起误解。

展开阅读全文

本文系作者在时代Java发表,未经许可,不得转载。

如有侵权,请联系nowjava@qq.com删除。

编辑于

关注时代Java

关注时代Java