专栏首页多选参数可读代码编写炸鸡三 - 审美

可读代码编写炸鸡三 - 审美

大家好,我是多选参数的一员 —— 大炮。

在上一篇 可读代码炸鸡二(下篇) - 命名的歧义 的结尾处,提到了接下来的炸鸡会围绕 多行代码,多个函数 的代码范围来讨论代码可读性的优化。

由这个思路走的话,那么接下来的炸鸡大致会分成两个内容:

  • 代码审美
  • 代码注释

所以本篇炸鸡将讨论 代码审美 对于可读性的作用。

原则

  • 一致布局,让读者很快习惯。
  • 相似代码看起来要相似。
  • 相关代码分组分块。

需要区分于设计

这只是代码外观组织上的优化,并非代码内部逻辑结构的重构优化。

但是审美上的要求在一定程度上会影响到代码内部逻辑结构。

为啥审美重要

喏,实践出真知。明显如下代码就是很差劲的代码编写。

class hamBurgerShop {
    public:
    // 敌无不斩,斩无不断
void Add(double d); // 增加一个东西
    private: int count; /* 多少
    */ public:
double Average();
    private: double minimum;
    list<double>
    past_items
    ;double maximum;
};

然后做一点审美层面的修改,你再看看,可读性瞬间提高。

// 汉堡店类 - 其实这个注释不用加。
class hamBurgerShop {
    public:
    void Add(double d);
    double Average();
    private:

    list<double> past_items;
    int count; // 多少个汉堡

    double minimum;
    double maximum;
};

代码中提到了一件事,也作为一个问题抛给大家。

为什么汉堡店类不需要注释?

这个问题会留到下一篇或者下下一篇炸鸡给出一些见解。

换行要一致且紧凑

首先我们设想一下这样的代码,生成两个 Fort 对象。但由于代码过长,可能会让你不断地使光标向右来查看完整代码(当然即使使用 vim 也得不断地按键),不能让阅读者同屏阅读代码,增加阅读者负担。

local fort1 = Fort.new("k1", 2222, 300, 4000, true, true)
local fort2 = Fort.new("super kingdom fort", 22256, 300, 4400, true, false, ...) -- 更加地长
if xxx then
    Log("xxx", shellNum)
end

还有《The Art of Readable Code》中提到的例子,同样是代码过长造成的阅读负担。

public class PerformanceTester {
    public static final TcpConnectionSimulator wifi = new TcpConnectionSimulator(500,80, 200, 1);
    public static final TcpConnectionSimulator t3_fiber = new TcpConnectionSimulator(500,80, 0, 0);
}

所以这时候换行就体现出作用了。

local fort1 = Fort.new("k1", 2222, 300, 4000, true, true)
local fort2 = Fort.new("super kingdom fort", 22256,
                        300, 4400, true, false, ...)
//一种换行
public class PerformanceTester {
    public static final TcpConnectionSimulator wifi = new TcpConnectionSimulator(500,
                                                            80, 200, 1);
    public static final TcpConnectionSimulator t3_fiber = new TcpConnectionSimulator(500,
                                                            80, 0, 0);
}

//又一种换行
public class PerformanceTester {
    public static final TcpConnectionSimulator wifi
    = new TcpConnectionSimulator(500,80, 200, 1);
    public static final TcpConnectionSimulator t3_fiber
    = new TcpConnectionSimulator(500,80, 0, 0);
}

这样便将代码长度控制在可视范围内。但是相同作用的两行代码,却不一定能体现相同的参数位置,这样也会对阅读者造成一定影响。所以我们可以将换行变得一致且紧凑

local fort1 =
    Fort.new(
    "k1",
    2222,
    300,
    4000,
    true,
    true)
local fort2 =
    Fort.new(
    "super kingdom fort",
    22256,
    300,
    4400,
    true
    false,
    ...)
public class PerformanceTester {
    public static final TcpConnectionSimulator wifi =
        new TcpConnectionSimulator(
            500,    /* Kbps */
            80,     /* millisecs latency */
            200,    /* jitter */
            1       /* packet loss % */);
    public static final TcpConnectionSimulator t3_fiber =
        new TcpConnectionSimulator(
            45000,  /* Kbps */
            10,     /* millisecs latency */
            0,      /* jitter */
            0       /* packet loss % */);
    public static final TcpConnectionSimulator cell =
        new TcpConnectionSimulator(
            100,    /* Kbps */
            400,    /* millisecs latency */
            250,    /* jitter */
            5       /* packet loss % */);
}

当然,这在一定程度上增加了代码行数,所以不要过度使用这样的规则。同时如果需要多次使用这样的方法,是否需要思考一下,你的代码内部是否需要优化?是不是代码内部成为了庞大的超级工厂

你可以选择优化代码结构,抽出更多的函数,或者可能需要一定的设计模式的内容,感兴趣的朋友可以自行查阅相关书籍与资料。

回想一下开头的原则,相似的相似,一致的布局。

同时需要提一嘴的是:

这个注释存在的意义是为参数加入更多的信息,例如上述代码是为了告诉阅读者参数的单位值。若参数命名表达的信息足够完整,不用增加这样的注释。当然这个问题在后头的炸鸡中我会详细说明。

但是这个注释和换行过于重复。我们可以将说明信息放到顶部,具体的如下所示。将函数名和参数列出,同时还列出参数具体意思。

public class PerformanceTester {
    // TcpConnectionSimulator(throughput, latency, jitter, packet_loss)
    //                          [Kbps]      [ms]    [ms]    [percent]

    public static final TcpConnectionSimulator wifi =
        new TcpConnectionSimulator(500, 80, 200, 1);
    public static final TcpConnectionSimulator t3_fiber =
        new TcpConnectionSimulator(45000, 10, 0, 0);
    public static final TcpConnectionSimulator cell =
        new TcpConnectionSimulator(100, 400, 250, 5);
}

用封装方法来清除不太好看的东西

什么叫做不太好看?

例如四处使用重复的代码。

function giveItem(itemId, amount, srcUserUid, destUserUid, needSync)
end

function Map:addNeedFood2user(uid)
    local count = 0
    for _, city in pairs(self._cities) do
        if exp1 then count = count + 1 end
    end

    local needFood = self:baseFood() * 0.8 + count ^ 2 *0.12
    call2User(uid, "addFood", needFood)
end

function Map:isNeedExpand()
    local count = 0
    for _, city in pairs(self._cities) do
        if exp1 then count = count + 1 end
    end
    if count > 400 then
        return true
    else
        return false
    end
end

我们可以看到,这一个逻辑是都有用到的。

local count = 0
for _, city in pairs(self._cities) do
    if exp1 then count = count + 1 end
end

所以我们将这个逻辑封装和抽象,方便阅读者理解,同时方便了复用。

function Map:fetchCityNum()
    local count = 0
    for _, city in pairs(self._cities) do
        if exp1 then count = count + 1 end
    end
    return count
end

function Map:addNeedFood2user(uid)
    local count = self:fetchCityNum()
    local needFood = self:baseFood() * 0.8 + count ^ 2 *0.12
    call2User(uid, "addFood", needFood)
end

function Map:isNeedExpand()
    local count = self:fetchCityNum()
    if count > 400 then
        return true
    else
        return false
    end
end

我们再举一个例子。

如果多个相同函数执行,但是由于参数长短问题,使得代码整体,有的换行,有的太短,参差不齐。

我直接使用《The Art of Readable Code》的示例:

DatabaseConnection database_connection;
string error;
assert(ExpandFullName(database_connection, "Doug Adams", &error)
== "Mr. Douglas Adams");
assert(error == "");
assert(ExpandFullName(database_connection, " Jake Brown ", &error)
== "Mr. Jacob Brown III");
assert(error == "");
assert(ExpandFullName(database_connection, "No Such Guy", &error) == "");
assert(error == "no match found");
assert(ExpandFullName(database_connection, "John", &error) == "");
assert(error == "more than one result");

所以可以多封装一层函数,将代码规整。

void CheckFullName(string partial_name,
                   string expected_full_name,
                   string expected_error) {
    // database_connection is now a class member
    string error;
    string full_name = ExpandFullName(database_connection, partial_name, &error);
    assert(error == expected_error);
    assert(full_name == expected_full_name);
}

这样先前繁杂代码可以变成如下清爽的代码。

CheckFullName("Doug Adams", "Mr. Douglas Adams", "");
CheckFullName(" Jake Brown ", "Mr. Jake Brown III", "");
CheckFullName("No Such Guy", "", "no match found");
CheckFullName("John", "", "more than one result");

这样不仅去除了重复的代码,而且阅读代码的时候一目了然,增加新的一行代码只要如法炮制即可。

所以上述例子或多或少证明了如果编写者对于代码审美做了要求,那么在一定程度上会优化代码的组织

善用列对齐

列对齐针对多个重复的函数的参数列表,可以起到代码规整的作用。如上文的多行 CheckFullName 函数,经过列对齐的修饰,会更加清楚:

CheckFullName("Doug Adams"  , "Mr. Douglas Adams"   , "");
CheckFullName(" Jake Brown ", "Mr. Jake Brown III"  , "");
CheckFullName("No Such Guy" , ""                    , "no match found");
CheckFullName("John"        , ""                    , "more than one result");

或者多列赋值的时候,也可以起到同样作用。

details     = request.POST.get('details')
location    = request.POST.get('location')
phone       = request.POST.get('phone')

当然,一些复杂数据结构的赋值,也可以利用。

local t = {
    {"timeout",     1,      "shshshsh"},
    {"timeout",     2,      "hsh"},
    {"ti",          3,      "shshshsh"},
    {"tries",       4,      "shsh"},
    ...
}

用一个顺序来写代码

  1. 最重要的语句最上,然后依次根据重要性的递减来排列语句。
  2. 按照字母顺序来排列
  3. 如果代码中提到了 A, B, C 三种命名,如果在同一个范围内(例如函数)再次使用了它们,调用顺序也保持一致。

第三种个人觉得较为普遍。我来解释一下。

假如一个代码需要三个步骤执行:

function test()

    ...
    ...
    firstStep:start()
    secondStep:start()
    thirdStep:start()
end

那么他们的相关变量的声明也根据这个顺序进行声明。

function test()
    local firstStep  = first:new()
    local secondStep = second:new()
    local thirdStep  = third:new()

    ...
    ...

    firstStep:start()
    secondStep:start()
    thirdStep:start()
end

分层或者分组思想

人更接受好的分组和层次,代码的过分堆砌,会使得阅读理解不太方便。例如下方列出的代码,看着难免有点费力:

class FrontendServer {
public:
    FrontendServer();
    void ViewProfile(HttpRequest* request);
    void OpenDatabase(string location, string user);
    void SaveProfile(HttpRequest* request);
    string ExtractQueryParam(HttpRequest* request, string param);
    void ReplyOK(HttpRequest* request, string html);
    void FindFriends(HttpRequest* request);
    void ReplyNotFound(HttpRequest* request, string error);
    void CloseDatabase(string location);
    ~FrontendServer();
};

许多人编写程序都有一个模块化的习惯,封装的方式取决于多次出现或者说可复用的代码量。

代码量

封装方式

函数

模块

所以分层分组的思想,这其实就是将代码的编写逻辑分模块。是在代码量更小的情况下,不至于上升至封装为函数的时候,对代码逻辑的的一个模块化,让 A 块代码做的事情为一组,B 块代码做的事情为一组。

这个思想主要体现在多个变量声明,函数定义的时候,例如类的定义。利用注释和分段,将不同组或者说不同层次的声明分开。

class FrontendServer {
public:
    FrontendServer();
    ~FrontendServer();

    // Handlers
    void ViewProfile(HttpRequest* request);
    void SaveProfile(HttpRequest* request);
    void FindFriends(HttpRequest* request);

    // Request/Reply Utilities
    string ExtractQueryParam(HttpRequest* request, string param);
    void ReplyOK(HttpRequest* request, string html);
    void ReplyNotFound(HttpRequest* request, string error);

    // Database Helpers
    void OpenDatabase(string location, string user);
    void CloseDatabase(string location);
};

同样,利用注释和分段,对一段逻辑代码进行总结和分段。

一开始代码如下:

def make_a_hamburg():
    vegetable = Vegetables()
    meat      = Meat()
    bread     = Bread()
    kitchen   = Kitchen()
    kitchen.wash(vegetable)
    kitchen.cook(bread)
    kitchen.cook(meat)
    return kitchen.get_a_hamburg()

修改的代码如下,找的例子的确有点好玩,但是就是讲的这个分层次和总结的意思。

def make_a_hamburg():
    # 准备食材
    vegetable = Vegetables()
    meat      = Meat()
    bread     = Bread()

    # 找好厨房
    kitchen   = Kitchen()

    # 开始制作
    kitchen.wash(vegetable)
    kitchen.cook(bread)
    kitchen.cook(meat)

    # 做好一个汉堡
    return kitchen.get_a_hamburg()

当然,这个方法容易使得空行比较多。我主程就要求我们尽量不要有空行,保持紧凑。

我个人觉得,如果能够很好地将代码有层次性地分开,多加空行是可以的;但如果加空行并不能达到这个效果,那只是徒增阅读者麻烦。

所以最终还是就 是否可读性,使得阅读者理解更快理解 这一标准衡量。

个人风格和项目风格一致性

Consistent style is more important than the 「 right 」 style.

当然,每个项目有都有自己规定的一套风格,即使可能不太正确,但是尽量和这个风格保持一致。

保持项目风格一致,比坚持个人风格更重要,不然杂乱在一起,看的更难受。

小结

  • 如果相似代码多次出现,就要考虑封装它们。
  • 代码中变量的声明顺序可以按照首字母顺序,重要程度来排列。当然,还有自定义的顺序,如果是自定义,这就需要声明的变量的顺序和调用变量的顺序尽量保持一致,体现出自定义顺序的严谨。
  • 善用注释和空行来将代码依据逻辑,功能作用等,进行分层,是一种更微型的模块化。
  • 哦对了,列对齐可以规整多行赋值语句,还可以说明函数作用和参数信息。

本文分享自微信公众号 - 多选参数(zhouxintalk),作者:大炮

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2020-03-27

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 可读代码编写炸鸡八 - 变量兜兜转转像是一场梦

    在一段时间后,多选参数会搞一个抽奖福利,其中是有《可读代码编写的艺术》以及其他书籍(可能还有别的) 的福利。可以先关注「 多选参数 」,以方便第一时间参与抽奖。

    syy
  • MySQL 架构与历史

    本篇是村民新坑的开始,村民最近在看《 高性能 MySQL 》这本书,村民在看的是第三版,仅涵盖 MySQL 5.5,虽然最新的 MySQL 已经是 8.0 版本...

    syy
  • vue 学习笔记第四弹 - Webpack

    webpack 是前端的一个项目构建工具,它是基于 Node.js 开发出来的一个前端工具;

    syy
  • 第二十节 netty源码分析之 reactor中的EventLoop01

    (如果使用到的是 NIO, 那么通常是 NioEventLoopGroup), 那么这个 NioEventLoopGroup 在 Netty 中到底扮演着什么角...

    用户1418372
  • 11 - JavaSE之GUI

    PS: Panel 的 setBounds 方法中设置的位置大小是相对于相对装入的 Frame 窗口位置和大小的。

    Daotin
  • C++蛇形矩阵算法

    它由1开始的自然数依次排列成的一个矩阵上三角形、环形或对角线等的走法,输入文件由一行或多行构成,每行由一个正整数N组成(N不大于100)。在程序设计时需要运用到...

    老九学堂-小师弟
  • 47. 光学计算 - 高效获取光传输矩阵

    本文同步发表在我的微信公众号和知乎专栏“计算摄影学”,欢迎扫码关注,转载请注明作者和来源

    HawkWang
  • CRUD很无聊?一起学设计模式吧!--策略模式

    策略模式属于对象的行为模式。其用意是针对一组算法,将每一个算法封装到具有共同接口的独立的类中,从而使得它们可以相互替换。策略模式使得算法可以在不影响到客户端的情...

    JAVA日知录
  • 从数据库中查询马上过生日的人并统计各年龄段及性别所占的人数

    wsuo
  • SpringMVC源码解析(一)

    为了简单起见,再一个就是现在这个年代也没有啥项目使用JSP了。所以本次分析使用SpringBoot结合thymeleaf来搞

    Java学习录

扫码关注云+社区

领取腾讯云代金券