[Refactoring] 編寫可讀代碼 筆記

• 目標: 給未來的自己看懂
• 方法: 
• First level: 外在 - naming, alignment
• Naming
• 使用精確的詞: e.g. search / load / …
• get/set 帶有 lightweight 的概念
• first/last 代表範圍內頭與尾的指標, begin/end 來表示範圍外的指標
• 避免 tmp, retval 等沒有解釋性的參數名詞
• Alignment
• 用 function / macro 等來對齊程式
• Group 不同目的的 function lists
• Constructors / deconstructors
• Getter / setters
• helper functions
• 使用段落來註解程式
• // 1. register database
• // 2. init
• // 3. CRUD operations
• // 4. release resources
• Comments
• 移除沒有意義的註解, e.g. variable name has explained
• 留下設計理念與意圖的註解 (全局觀)
• 留下 limitation / FIXME / TODO
• 提供 example (UT)
• Second level: control flow
• loops
• 避免 do-while (except marco using do-while(0))
• 大多時候避免 goto function
• 最小化 embedded loops
• Expressions / variables
• 利用暫存的解釋變量減少長表達式, 但有時反過來要移除沒必要的中間變量
• 盡可能縮小 variable scope (避免 global variables)
• 善用 marcos 縮短表達式長度
• Third level: 模組化
• 善用 utility functions 來做到模組化
• 利用 wrapper function 簡化 interface
• 各 function 一次只做一件事
• 熟悉既有 libraries
• 善用 scripts 處理簡單工作, e.g. awk parse logs
• Others:
• Test-driven
• Sample refactoring flow: from naïve solution to complete solution
• 延伸閱讀
• "Code Complete: A Practical Handbook of Software Construction, 2Ed", Steve McConnell
• "Refactoring: Improving the Design of Existing Code", Martin Fowler
• "The Practice of Programming", Brian Kernighan and Rob Pike
• "Clean Code: A Handbook of Agile Software Craftsmanship", RobertC. Martin
• "Design Patterns: Elements of Reusable Object-Oriented Software", Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides
• "Programming Pearls, 2Ed", Jon Bentley

[Code Review] Check pointer not null

• C 語言有非常強大的 pointer, 但也因此惡名昭彰
• 兩個常用的情況是
• Null pointer check

    	if (ptr != NULL) {
        	// do something ...
        } else {
        	// error handling
        }
    

• 其中就相當多可以討論的地方
• 要用 if (ptr) 還是 if (ptr != NULL) 還是 if (NULL != ptr)
• 建議使用 if (ptr) 就好, 幾個理由如下
• If (ptr ==) 類型的 check, 可能會少寫一個 =, 變成 assignment, 造成難追的 bug
• NULL 的 implementation 未明確定義, 依不同 compiler 可能實作成 ((char *)0), ((void *) 0), 0, 0L 等
• 相容於 smart pointer return bool 的 check
• 降低不必要的 compare
• Reference: Checking for null pointer in c
• Memory leak
• C++ 引入了 unique_ptr, shared_ptr, weak_ptr 等smart pointers
• Auto release resource at desstructor

[Astyle] Code Formatter

# astyle setting
# ref: http://astyle.sourceforge.net/astyle.html
#alias astyle='astyle -A1 -C -S -K -Y -f -p -U -o -n'
# options:
# --style=allman / --style=bsd / --style=break / -A1    // { at new line
# --indent=spaces=4 / -s4
# --indent-col1-comments / -Y   // indent comments
# --pad-oper / -p               // a=4 to a = 4
# --pad-header / -H             // if(i = 4) to if (i = 4)
# --delete-empty-lines / -xe
# --align-pointer=name   / -k3  // char* a; int *b; to char *a; int *b;
# --align-reference=name   / -W3
# --attach-return-type      / -xf // void     foo(); to void foo();
# --attach-return-type-decl / -xh
# --max-code-length=#   / -xC#   // ref: https://google.github.io/styleguide/cppguide.html#Line_Length
# --mode=c                      // only formatted on C/C++ files
# --suffix=none / -n            // do not copy additional .orig file
# --verbose / -v
# --lineend=linux   / -z2
# --indent-switches / -S
# --break-blocks / -f           // add empty line before/after if/for/while blocks
alias astyle='astyle -A1 -s4 -Y -p -H -xe -k3 -W3 -xf -xh -xC80 -n -z2 --mode=c -S -f'

Reference: 

• Source Insight 外掛 Artistic Style 程式碼自動格式化
• using astyle with visual studio
• Artistic Style (official website)