定义明确的参数名/变量名--许多时候，授人以渔还真不如直接授人以鱼

定义明确的参数名/变量名，是软件开发中的一个重要准则。但是，总这么强调，起的作用似乎并不大。许多时候，授人以渔还真不如直接授人以鱼。

所以，我们具象化，看一个栗子。

下面是一个业务服务类UserTagService中的一个私有方法。这个方法控制业务逻辑并调用仓储类UserTagManager实现向user_tag表批量新增数据。 user_tag表是用户技能标签表，字段包括 用户id、用户名（user_name）、用户身份证号、技能标签名（tag_name）。

private void addUserTagByUser(User user, List<String> tagNameList) {
    log.info("用户添加标签入参信息，当前用户id[{}]，标签信息[{}]", user.getUserId(), JSON.toJSONString(tagNameList));
    Assert.notNull(user.getUserId(),"添加标签，用户id不可为空");
    if (CollectionUtils.isEmpty(tagNameList)) {
        return;
    }
    
    List<UserTag> newInsertList = new ArrayList<>();
    for(...) {
        if (StringUtils.isNotBlank(name) && existTags.add(name)) {
            newInsertList.add(userTagManager.buildEntity(user.getUserId(), user.getIdcardNo(), name));
        }
    }
    userTagManager.saveBatch(newInsertList);
}

注意这段代码中的 name 变量。 调用userTagManager.buildEntity 方法传的第3个参数 name，如果不看上下文，以及这个 userTagManager#buildEntity 方法的定义，可能会让阅读者搞不清这个 name 代表的是用户名 还是 技能标签名。

下面再看 UserTagManager类里这个 buildEntity 方法的定义。碰巧它的第三个参数名也叫 name， 如此，只能通过方法实现才能得知这个 name 是技能标签名。

public UserTag buildEntity(Long userId, String idCardNo, String name){
    final UserTag userTag = new UserTag();
    userTag.setUserId(userId);
    ...
    userTag.setTagName(name);
    ...
    return userTag;
}

因此，我们有必要将这两段代码中的模棱两可的 name 明确定义为 tagName。产品设计上有一条重要的「Don't Make Me Think」原则，强调用户体验设计中的直观性和易用性，旨在减少用户在使用产品时的思考负担。这一核心思想同样适用于软件开发、软件设计。细微之处见“匠心”呀！

private void addUserTagByUser(User user, List<String> tagNameList) {
    ...
    for(...) {
        if (StringUtils.isNotBlank(tagName) && existTags.add(tagName)) {
            newInsertList.add(userTagManager.buildEntity(user.getUserId(), user.getIdcardNo(), tagName));
        }
    }
    ...
}

public UserTag buildEntity(Long userId, String idCardNo, String tagName){
    final UserTag userTag = new UserTag();
    ...
    userTag.setTagName(tagName);
    ...
    return userTag;
}