buguge - Keep it simple,stupid

知识就是力量,但更重要的,是运用知识的能力why buguge?

导航

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

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

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

下面是一个业务服务类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;
}

posted on 2024-10-22 09:27  buguge  阅读(17)  评论(0编辑  收藏  举报