Clean Code 讀後感想

重點如下：

1. Clean Code 追求的層次與境界比 Coding Rule 和 Coding Style 高，特別是程式碼的可讀性與易理解性，所以有講到程式碼的整體結構與佈局。

2. PG 的英文一定要很好，因為在這個指導原則下，寫 code 其實就好像是在用英文寫文章了（語境、語法、格式、段落、措辭、編排...等等都要考慮到）。

3. 要懂什麼是 S.O.L.I.D 五大原則，也要知道一些 Design Patterns（所以你應該也已經懂 UML 了）。

4. 也要懂 Refactoring、TDD、AOP...等等概念，所以建議搭配 Kent Beck 和 Martin Fowler 和其他一些大師的理念一起服用，效果會更佳。

5. 本書的舉例和引用都是 Java，所以比較適合 Java Programmer 閱讀，其他語言未必完全適用（除了像一些通則以外，如命名、註解、編排...等）。

6. 這本書至少要看過兩次以上，也要不停地練習、自我檢討才能內化為直覺反應。（也可能是我資質比較駑鈍吧，呵⋯）

以上都只是「專業知識技能」的部分，基本上還可以籍由後天的培訓來補足。這樣才可以說「慬」Clean Code。

但是真正要「做到」Clean Code，我覺得主要還是取決於個人的道德良知與自我嚴格要求，而這部分會比較偏人格特質的方面（沒錯，最好是有潔癖）。

若要 enforce 至公司內部 PG 團隊，則團隊裡的每個人都必須符合上述條件。否則，總是有人會一再地把 code 弄髒。此外，平時彼此之間要互相監督、提醒才行。

那如果要 enforce 至外包 PG 團隊呢？我覺得這就滿困難的了。因為在這種情況下，公司不太可能會對外包人員施以教育訓練，也無從了解其人格特質。

若公司派一個具備 Clean Code 能力的人全時間去督導呢？這不僅不符合成本效益，也是比較消極被動的控管方式。況且業界的驗收標準也尚未有所謂的 Clean Code 標準可茲依循遵守。

（外包：我不是只要功能、效能、資安都達到要求就好了嗎？怎麼現在還要要求我寫的 Code 是夠 Clean 呀!?）

將 DocBook 轉換成 PDF 格式

這是上一篇文章「DocBook 的 Line Numbering 和 Code Highlighting」的續集，今天我們要將 DocBook 輸出為 PDF 格式，但在這邊要先提醒一下：Apache FOP 似乎不認得 xslthl 轉出來的 tags，所以如果你想將 DocBook 輸出成 PDF，可能就要先放棄 Code HighLighting 的功能。小弟自己在嘗試過多次以後，已經宣告放棄了...XD

我本身使用的 OS 是 Windows 7 Pro 64bit，JVM 版本則是 Oracle JDK 1.6.0_43，建議您盡量採用和我一樣的環境與軟體版本，以免遭遇到其他問題。

接下來進入正題，開始說明轉換的步驟：

一、FOP 的取得、安裝及設定

請到「http://archive.apache.org/dist/xmlgraphics/fop/binaries/」下載 fop-1.0-bin.zip，因為我只試過這個版本，而且沒遇到什麼問題，所以建議您跟我採用一樣的版本吧！

跟上一篇文章一樣，也請解壓縮在「D:\docbook」下方，所以這個資料夾下方應該要長的像下面這樣才對：

• docbook-xsl-1.78.1\
• fop-1.0\
• output\
• saxon6-5-5\
• tools\
• xerces-2_11_0\
• xslthl-2.1.0\
• my_article.xml
• my_article.xsl
• my_code.java 

接下來，請修改「D:\docbook\fop-1.0\conf\fop.xconf」的內容，在「renders/render/fonts」區段加入如下內容（ START 到 END 之間），讓  FOP 可以使用你系統內的字型（包含中文字型），這部分我是參考「Docbook开发手记」的：

<fop version="1.0">
    ...
  <renderers>
    <renderer mime="application/pdf">
        ...
      <fonts>
        ...
        
        <!-- START -->
         <!-- register all the fonts found in a directory and all of its sub directories (use with care) -->
         <directory recursive="true">file:///c:/windows/fonts/</directory>

         <!-- automatically detect operating system installed fonts -->
         <auto-detect/>
        <!-- END -->
      </fonts>

二、修改 my_article.xsl：

請將 my_article.xsl 替換成如下的內容：

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:saxon="http://icl.com/saxon"
                extension-element-prefixes="saxon"
                version='1.0'>
 
<xsl:import href="file:///D:/docbook/docbook-xsl-1.78.1/fo/docbook.xsl"/>
 
<!--=====================================​=======================================
line numbering
====================================================​=========================-->
<xsl:param name="linenumbering.everyNth">1</xsl:param>
<xsl:param name="linenumbering.width">4</xsl:param>
<xsl:param name="linenumbering.separator"><xsl:text> </xsl:text></xsl:param>

<!--====================================================​========================
font setting
====================================================​=========================-->
<xsl:param name="title.font.family">Microsoft JhengHei</xsl:param>
<xsl:param name="body.font.family">Microsoft JhengHei</xsl:param>
<xsl:param name="monospace.font.family">MingLiU</xsl:param>
<xsl:param name="symbol.font.family">Cambria Math</xsl:param>

<!-- add bookmark and support more type of figure -->
<xsl:param name="fop1.extensions">1</xsl:param>

<!-- no indent for body content -->
<xsl:param name="body.start.indent">0pt</xsl:param>

</xsl:stylesheet>

三、使用以下指令進行轉換（在「D:\docbook」下面）：

1. 先使用 Saxon 或 Xalan 來產生 fo 檔：

Saxon：

java -cp "D:\docbook\saxon6-5-5\saxon.jar;D:\docbook\docbook-xsl-1.78.1\extensions\saxon65.jar" com.icl.saxon.StyleSheet -o output\my_article.fo my_article.xml my_article.xsl use.extensions=1

Xalan：

java -cp "D:\docbook\tools\xalan.jar;D:\docbook\xerces-2_11_0\xml-apis.jar;D:\docbook\xerces-2_11_0\xercesImpl.jar;D:\docbook\docbook-xsl-1.78.1\extensions\xalan27.jar" org.apache.xalan.xslt.Process -OUT output\my_article.fo -IN my_article.xml -XSL my_article.xsl -L -PARAM use.extensions 1

產生的 fo 檔案位於「D:\docbook\output\my_article.fo」。

2. 再以 fop.bat 指令將 fo 檔轉成  PDF 檔：

fop-1.0\fop.bat -c d:\docbook\fop-1.0\conf\fop.xconf -fo output\my_article.fo -pdf my_article.pdf

產生的 PDF 檔案在「D:\docbook\my_article.pdf」。在執行的過程中，我是有看到一些錯誤訊息（請參考本文最下方），但是最終產生的 PDF 看起來是正常的，所以應該沒什麼關係。

我這邊轉出來的檔案就像下面這個樣子，希望你也成功了。

my_article.pdf

和上一篇文章遭遇的問題一樣，Xalan 在轉換外部檔案「my_code.java」時，即使有在 <textdata> 標籤加上「encoding="UTF-8"」屬性，中文（在註解的位置）仍會變成亂碼，但 Saxon 就不會。

如果您還想更深入瞭解 DocBook ，建議再參考以下這些網站：

• DocBook 文件寫作入門
• Docbook开发手记
• DocBook: The Definitive Guide
• DocBook XSL: The Complete Guide
• DocBook XSL Stylesheets: Reference Documentation

總結來說，DocBook 確實是一套很不錯的文件格式標準（可以轉換成不同的文件格式），個人認為比較可惜的是：(1) 許多相關的文件與資料都已經很舊、過時了，(2) 相關的社群似乎也不再熱絡了。所以每次遇到問題時、要找答案或解決方式，都很困難...

附錄、執行 FOP 時看到的錯誤訊息

D:\docbook>fop-1.0\fop.bat -c d:\docbook\fop-1.0\conf\fop.xconf -fo output\my_ar
ticle.fo -pdf my_article.pdf
2013/8/3 下午 04:53:55 org.apache.fop.apps.FopFactoryConfigurator configure
資訊: Default page-height set to: 11in
2013/8/3 下午 04:53:55 org.apache.fop.apps.FopFactoryConfigurator configure
資訊: Default page-width set to: 8.26in
2013/8/3 下午 04:53:56 org.apache.fop.events.LoggingEventListener processEvent
警告: Font "Cambria Math,normal,700" not found. Substituting with "Cambria Math,
normal,400".
2013/8/3 下午 04:53:57 org.apache.fop.hyphenation.Hyphenator getHyphenationTree
嚴重的: Couldn't find hyphenation pattern zh_tw
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: This is a TrueType collection file with 3 fonts
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: Containing the following fonts:
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU <-- selected
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: PMingLiU
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU_HKSCS
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: This is a TrueType collection file with 3 fonts
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: Containing the following fonts:
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU <-- selected
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: PMingLiU
2013/8/3 下午 04:53:57 org.apache.fop.fonts.truetype.TTFFile checkTTC
資訊: MingLiU_HKSCS