程式碼的可讀性比較

by thinker

關鍵字:

以下就程式碼的可讀性即其產生之 binary 進行分析。依其順序，逐漸改進其可讀性。透過比較，我們能較透澈的了解可讀性的性質。

下面的程式，是一個分析 HTTP request line 的 parser 。 Request line 的格式如下
{{{
GET /path/to/resource HTTP/1.1
}}}
程式的目的是將 request line 裡的三個欄位，分別取出為 method 、 uri 和 protocol 。

== 程式一 ==
最平舖直訴的方式，這大概是每個 programmer 都會經過的階段吧!!
{{{#!cpp
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

typedef struct {
    char *method;
    char *uri;
    char *proto;
} http_req;

int http_req_parse(http_req *req, const char *buf, int sz) {
    int i, prev;
    
    for(i = 0; i < sz; i++) {
        if(buf[i] == ' ') break;
        if(buf[i] == '\n' || buf[i] == '\r')
            return -1;
    }
    if(i == sz || i == 0) return -1;
    req->method = (char *)malloc(i + 1);
    strncpy(req->method, buf, i);
    req->method[i] = 0;
    
    prev = ++i;
    for(; i < sz; i++) {
        if(buf[i] == ' ') break;
        if(buf[i] == '\n' || buf[i] == '\r') break;
    }
    if(i == sz || i == prev || buf[i] != ' ') {
        free(req->method);
        return -1;
    }
    req->uri = (char *)malloc(i - prev + 1);
    strncpy(req->uri, buf + prev, i - prev);
    req->uri[i - prev] = 0;
    
    prev = ++i;
    for(; i < sz; i++) {
        if(buf[i] == ' ') break;
        if(buf[i] == '\n' || buf[i] == '\r') break;
    }
    if(i != sz || i == prev) {
        free(req->method);
        free(req->uri);
        return -1;
    }
    req->proto = (char *)malloc(i - prev + 1);
    strncpy(req->proto, buf + prev, i - prev);
    req->proto[i - prev] = 0;
    
    return 0;
}

int main(int argc, const char *argv[]) {
    const char *data = "GET /$test$.html HTTP/1.1";
    http_req req;
    
    if(http_req_parse(&req, data, strlen(data)) < 0) {
        fprintf(stderr, "error to parse request line!\n");
        return 1;
    }
    
    printf("request line: %s\n", data);
    printf("method: %s\n", req.method);
    printf("uri: %s\n", req.uri);
    printf("protocol: %s\n", req.proto);
    
    return 0;
}
}}}

== 重複的動作 ==
將不斷重複的動作取出，並定個有意義的名稱。如此程式不但變小，而且因為 function 名稱所帶來的意涵，加強了程式的可讀性。由此可知，將程式的部分流程變成 function ，並附于適當的名稱，能改善程式的可讀性。

strncspn() 其實就是 strcspn() 的變形，可看 $Linux$ 或 $FreeBSD$ 的 man page 。而 strndup() 就是 strdup() 的變形。透過這些有意義的名稱，程式碼的流程更有意義，提供更多線索，更適合大腦解讀。

{{{#!cpp
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

typedef struct {
    char *method;
    char *uri;
    char *proto;
} http_req;

int strncspn(const char *s, int max, const char *charset) {
    int i, j, cs_sz;
    char c;
    
    cs_sz = strlen(charset);
    for(i = 0; i < max && s[i] != 0; i++) {
        c = s[i];
        for(j = 0; j < cs_sz; j++) {
            if(c == charset[j]) return i;
        }
    }
    return max;
}

char *strndup(const char *s, int max) {
    int sz = strlen(s);
    char *buf;
    
    if(sz > max) sz = max;
    buf = (char *)malloc(sz + 1);
    memcpy(buf, s, sz);
    buf[sz] = 0;
    
    return buf;
}

int http_req_parse(http_req *req, const char *buf, int sz) {
    const char *substr, *last, *next;
    int substr_sz;
    
    last = buf + sz;
    
    substr_sz = strncspn(buf, sz, " \r\n");
    if(substr_sz == sz || substr_sz == 0 || buf[substr_sz] != ' ')
        return -1;
    req->method = strndup(buf, substr_sz);
    
    substr = buf + substr_sz + 1;
    substr_sz = strncspn(substr, last - substr, " \r\n");
    next = substr + substr_sz;
    if(substr_sz == 0 || next == last || *next != ' ') {
        free(req->method);
        return -1;
    }
    req->uri = strndup(substr, substr_sz);
    
    substr = next + 1;
    substr_sz = strncspn(substr, last - substr, " \r\n");
    next = substr + substr_sz;
    if(next != last) {
        free(req->method);
        free(req->uri);
        return -1;
    }
    req->proto = strndup(substr, substr_sz);
    
    return 0;
}

== 邏輯拆離 ==
前面的程式，將 parse 的過程中的數個邏輯交叉混合在一起。下面的程式將這些邏輯個別分離，變成獨立的區塊。將相關邏輯集中處理，而非交錯在一起，導至讀者必需不斷的在邏輯之間切換。

另一方面，將邏輯拆離，能減少透過 variable 保留和傳遞資訊的狀況。如第一和第二個程式，透過變數 i  和 substr 保留和傳遞目前處理的狀態，以在 function 前後傳遞資訊。這迫使讀者必需追蹤 variable 的內容，才能理解每一段程式碼的作用和正確性。

而邏輯拆離後，條件判斷也減少了。使用條件式，經常是一種邏輯上的修補行為，對意外狀況的處置。然而大部分情況並非不可避免的，只需適當的安排，將邏輯拆離，既可避免這種修補的動作。

而邏輯拆離後，每一個程式碼區塊的功能也單純化。讀者更易理解，程式撰寫時，也更能確定程式的正確性。

下例，一開始先把確定換行符號是否在字串裡，以排除換行的狀況。接著取得空白符號的位置。最後複製字串，並成 method 、 uri 和 proto 的內容。

{{{#!cpp
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

typedef struct {
    char *method;
    char *uri;
    char *proto;
} http_req;

int http_req_parse(http_req *req, const char *buf, int sz) {
    const char *substr, *last;
    int i;
    const char *fss[4];
    
    sz = strncspn(buf, sz, "\r\n");
    last = buf + sz;
    
    substr = buf;
    for(i = 1; i < 4; i++) {
        fss[i] = substr + strncspn(substr, last - substr, " ");
        if(fss[i] == last) break;
        substr = fss[i] + 1;
    }
    if(i != 3)
        return -1;
    
    fss[0] = buf;
    fss[3] = last;
    for(i = 0; i < 3; i++) {
        if(i > 0) fss[i]++;
        if((fss[i + 1] - fss[i]) < 1)
            return -1;
    }
    
    req->method = strndup(fss[0], fss[1] - fss[0]);
    req->uri = strndup(fss[1], fss[2] - fss[1]);
    req->proto = strndup(fss[2], fss[3] - fss[2]);
    
    return 0;
}

== 再次簡化 ==
前一個程式將邏輯分離，這個程式將分離後的程式再改進。例如將重用性高的部分再取出，如 strnchrs() 其實就是 strchr 的變形，這樣的 function 功能單純，可重用性高。再加上賦于一個有意義的名稱，增加了程式的可讀性。

另外，把幾個 loop 替換成直接的 statement ，直接的陳述往往比 loop 和 condition 來的易讀。但，如果重複的次數太多時，當然使用 loop 才是合理的狀況。

{{{#!cpp
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

typedef struct {
    char *method;
    char *uri;
    char *proto;
} http_req;

int strnchrs(const char *s, int max, int c, const char *chrs[], int chrs_max) {
    int i, j = 0;
    
    for(i = 0; i < chrs_max; i++, j++) {
        for(; j < max; j++)
            if(s[j] == c) break;
        if(j == max) break;
        chrs[i] = s + j;
    }
    
    return i;
}

int http_req_parse(http_req *req, const char *buf, int sz) {
    int i;
    const char *last;
    const char *fss[3], *starts[3];
    
    sz = strncspn(buf, sz, "\r\n");
    last = buf + sz;
    
    if(strnchrs(buf, sz, ' ', fss, 3) != 2)
        return -1;
    
    starts[0] = buf;
    starts[1] = fss[0] + 1;
    starts[2] = fss[1] + 2;
    fss[2] = last;
    
    for(i = 0; i < 3; i++)
        if(starts[i] == fss[i]) return -1;
    
    req->method = strndup(starts[0], fss[0] - starts[0]);
    req->uri = strndup(starts[1], fss[1] - starts[1]);
    req->proto = strndup(starts[2], fss[2] - starts[2]);
    
    return 0;
}

== 行數 ==
表面上看來，改進可讀性之後，程式碼的行數突然大增。但是如果仔細算一下有意義的 statement 數目，其實是減少的。之所以會有大增的表象，是來自於 function 、 變數的宣告 、 呼叫和留白。但這些是否該例入程式的複雜度裡？本人採取否定的態度。我的計算方法，是將每一個 assign statement 算一行，每一個 for 、 if 、 break 、 return 、 continue 算一行。如此
{{{
if(...) break;
}}}
會算兩行。而 variable 和 function 的宣告不列入計算。

仔細算下來，最後一個程式比第一個程式還少上數行。

== 執行檔的大小 ==
{{{
-rwxr-xr-x  1 thinker  users  6117 May  6 00:06 readability0
-rwxr-xr-x  1 thinker  users  6161 May  5 20:58 readability1
-rwxr-xr-x  1 thinker  users  6064 May  5 21:30 readability2
-rwxr-xr-x  1 thinker  users  6125 May  6 00:06 readability3
}}}
依序為前面四個程式的大小。第四個程式的成本是區區數個 bytes ，但可讀性卻大幅的改善。另一方面，本程式規模較小，大程式的的重複性更高，增加可讀性可能會使程式比原來更小。程式愈大，其效能愈大。

== 結論 ==
程式的可讀性，來自於有意義的名稱、邏輯的分割。而可讀性卻不會增加程式的大小，反而能使程式更精簡、更小、甚至更快。本文並沒有討論到模組的計設和資訊封裝等議題，單就程式流程的可讀性進行討論。

最後更新時間: 2007-05-06 09:50:35 CST | 引用

查詢:

COMMENTS:

on 2012-01-06 18:00:44 CST

IKARi said ..

大推Thinker大的這篇好文！後面關於複雜度的討論，讓我想到最近在用的tool: Source Monitor, 可以評量一份source code的複雜度，而複雜度的metrics即是從code complete裡的定義而來如 C Metrics: https://gist.github.com/1569929 (格式沒有重新折行) stackoverflow的討論： How to interpret code metrics (calculated by SourceMonitor) - Stack Overflow http://stackoverflow.com/questions/134266/how-to-interpret-code-metrics-calculated-by-sourcemonitor tools - Calculate code metrics - Stack Overflow http://stackoverflow.com/questions/60394/calculate-code-metrics 也許可以參考看看！

on 2012-01-06 18:02:17 CST

IKARi said ..

sorry上篇留言格式有點亂，似乎沒辦法換行...

on 2012-01-06 18:05:07 CST

IKARi said ..

sorry上篇留言格式有點亂，似乎沒辦法換行...

on 2012-01-06 18:05:41 CST

IKARi said ..