Z05 版權宣告與註解範本的內容

撰寫程式碼除了code本身之外，每一支程式都必須要有的部分就是版權宣告與程式碼註解。每支程式最前端都會有我自己的版權宣告段落：

/*******************************************************************************
* Copyright (c) 2010 Joying Lee
*
* All rights reserved.
* This program is free to use, but the ban on selling behavior.
* Modify the program must keep all the original text description,
* and can only comment out the original code (not allowed to delete).
*
* 保留所有權利。
* 本程式可任意使用，但是禁止販售行為。
* 修改程式時必須保留所有原有文字說明，而且只能註解掉原來的程式碼 (不允許刪除)。
*
* My Blog : http://ooadreason.blogspot.com
*******************************************************************************/

註解的定義根據[V01]的描述，區分為Class、Field與Method三種；註解的本體目前定義有摘要、描述與使用三個部分，再往下則是@開頭的Java Doc常用標籤。整理為出一份自己要使用的關係對照表如下圖，接著遵循這些註解規則建立Eclipse內的Code Template並匯出XML作為往後使用的標準。



最後定義程式中描述處理過程的註解與變更時與Trac ticket相關的標記註解如下：

/* 這是描述處理過程的註解，必須獨立存在一行 */
// 這是與Trac ticket相關的標記註解，必須在程式碼那行的最後面

註：在以下範例程式的三個註解位置，似乎各自代表不同的意義。我的解讀是：
註解Ａ－描述if那個指令的判斷說明。
註解Ｂ－描述if成立後那個block的說明。
註解Ｃ－描述return那行的說明。
/* 註解A */
if (isTrue()) /* 註解B */ {
　　/* 註解C */
　　return;
}
若依照我的註解準則與未來模組化的目的，應該變成可讀性略差的這樣：
/* 註解A */
if (isTrue())
/* 註解B */
{
　　/* 註解C */
　　return;
}

參考網址：http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Z04 工欲善其事，必先利其器

新的年度開始，也該是進入新階段的時候。俗話說的好：工欲善其事，必先利其器，這句話的意思是說只要讓別人看到自己在準備工具，就會以為你要開始做事。咦？解釋的角度不對？總之，不管要不要做事，先把工具弄好就對了。

前陣子研讀Java Power Tool的經驗，剛好可以移植需要的部分到自己的開發環境。先列出必須要在Windows環境下安裝的應用程式：

●StarUML 5.0　下載網址：http://staruml.sourceforge.net/en/download.php
　Rational Rose不是每個人都有，還是使用免費軟體比較適合；這是我覺得比較適用的。
●JDK 6 Update 18　下載網址：http://java.sun.com/javase/downloads/widget/jdk6.jsp
　使用Java SE就能符合近期的需要。
●Eclipse 3.5.1　下載網址：http://www.eclipse.org/downloads/
　下載Java EE的版本。本來考慮用Modeling版本來畫UML，但是現在設計與開發還沒有很好的串接；也考慮使用可以開發plugin的Standard版本，這等到需要開發plugin工具時再說吧。
●VisualSVN 1.7.7　下載網址：http://www.visualsvn.com/visualsvn/download/
　Windows環境下很方便使用的SVN Server，安裝後可立即開始使用。暫時還不會用到版本控管，不過還是一起安裝。

以下是我在Eclipse裡安裝的plugin（在Eclipse上安裝plugin的方法請上網搜尋）：

●Subversive 0.7.8　安裝網址：http://download.eclipse.org/technology/subversive/0.7/update-site/
　版本控管的Client端。暫時還不會用到。
●Subversive Connector　選擇SVN Kit 3.0後會自動開始安裝。
●M2Eclipse 3.0.0　安裝網址：http://m2eclipse.sonatype.org/update/
　管理Maven專案的工具，除了plugin設定configuration還不能用之外是很方便的工具。在我的環境裡不打算安裝library server，直接上global repository同步。
●Java Doc：內建。
●Checkstyle 5.0.3　安裝網址：http://eclipse-cs.sf.net/update/
●PMD 3.2.6　安裝網址：http://pmd.sf.net/eclipse
●Findbugs 1.3.9　安裝網址：http://findbugs.cs.umd.edu/eclipse/
　以上三項是協助檢查程式碼是否符合一些常用規則的工具軟體。
●jUnit 4：內建。
●Eclemma 1.4.3　安裝網址：http://update.eclemma.org/
　檢查Unit Test涵蓋度的工具軟體。

Y10 用物來描述事，用事來成就物

Ant、Maven這兩個好用工具的廣受歡迎，有人點出是它們能夠利用檔案設定方式將專案進行中的瑣碎行為定義標準，在需要進行那件事的時候任何人只要執行它就可以得到完全一樣的結果。這種方式與將每個時間點要作的事記錄成SOP要求遵照進行比較，除了必須先行瞭解新的工具用法之外，帶來的卻是便利與穩定等強大好處。

當事情可以用人或電腦來處理時，不同人、不同時間的同樣操作都有較高的錯誤與不一致機率，這些問題在利用電腦處理時可以大幅降低，只需要花一次時間精確地定義出處理的詳細規則；觀察許多工具其原始目的大致如此。Ant對於單一事件（通常是build版本）定義出詳細的處理過程，而Maven更進一步地定義出專案管理中的幾個階段，再整合其他工具、加上與程式碼相關的物件（library、testing、reporting……等），建構起一個能夠調校的自動管理系統。

收集軟體專案開發必須要做的事，定義出每個軟體專案能通用的開發流程、階段與當時可以做的事，同時允許使用者設定使用一般常用的方便工具，得到適用的客製化結果。當工具符合專案大部分的自動化需求時，即使需要額外投入學習的時間還是會加以運用。

回到自己部落格的內容，現在記錄的資料只是根據過去的零碎的經驗值推想一些改進的方法，沒有全面的整理與比較根本說不出這麼做的最終目的。此時的思緒已經逐漸清楚，明白自己是想定義用程式碼製作出來的全部事與物都有完全一致的型式與規則。如果像專案開發階段這樣令人感覺抽象且發散的事都能夠依賴設定之物來運作，試圖將程式碼轉化為某種特別的設定來驅動更豐富的自動化解析也應該是可以達成的。

這，正是我想逐步實現的理想。

X12 精確地拆解、完全地對應(4)──記錄的內容

從寫計畫書時的拆解目標到記錄安裝手冊的步驟，最近感覺慢慢地開始喜歡撰寫文件。主要因為發現無論是目標的拆解或是一堆軟體的安裝，都是將許許多多的物與關聯運用平鋪直敍的方式來記錄；套用將人視為電腦的觀念，就像在制訂匯出的規範（決定匯出的順序與內容），讓匯出的資訊進到任何一個人都可以還原前人腦中的想法。

●第一個考慮的是全部的範圍。根據需要安裝的軟體、需要的環境設定、專案的參數定義與需要完成的特定事件來思考並加以歸類；未來每一個項目都要製作對應文件說明。在這裡可以想像是Use Case的定義與群組化，再加上循序漸進地順序佈置以建構閱讀者對整個平台的瞭解。

●對於每一個說明點的內容，意義上與用文字敍述的功能劇本差不了多少。準備的檔案與起始狀態、每一個步驟的忠實記錄並佐以圖檔、每一步驟後的狀態檢查、還有最後完成的狀態與驗證，都是需要記載於文件的內容。其中若有小目的需要用多個步驟才能完成，應加以群組起來說明較為清楚（很像是寫程式時將多行群組為一個方法）。

●有時會需要兩層式的文件才能說明一件事。例如建置一個Maven專案的流程要在Eclipse上新建Maven專案、設定subversion儲存庫再share project，倘使流程文件直接記錄每個步驟，就會發生其他流程要使用設定subversion儲存庫這個步驟的說明時，不知是要參照其中的步驟(只參考流程的一部分)還是自己建立新的說明（重覆的資料）好。我的解法是每個步驟都拆到對應軟體的操作手冊裡，再從流程內容參照過去；整個流程需要輸入的資料則記錄在流程文件裡，畢竟那是該流程特有的內容。

在移交開發平台的過程中，曾經為了兩個沒有記錄到的小步驟，用了一個工作天才感覺似乎少了些什麼，一天之後才確認真的有缺少。記錄兩個小步驟只是幾分鐘的時間，但是可以省下不應花費的一天；用這個例子提醒自己撰寫文件的價值與影響，自然會時常懷著戒慎恐懼的心態力求完整。

X11 精確地拆解、完全地對應(3)──經驗的留存

先讓別人明白為什麼要做這些事之後，接著要讓別人知道為什麼會有那些物。將焦點放在搭配工具的那一欄：所有使用工具的聯集就是開發平台上應該安裝的全部。開發平台會分為Client端與Server端，專案起始的環境建置應同時準備好這些。前面提到的安裝文件就是描述整個平台從無到有的建置過程。

從使用者的觀點來看，並不需要知道開發平台是怎麼樣被建置起來的，只要提供一個能讓他們根據規定流程做事的東西即可。然而從管理面來看，如果設定需要調整要怎麼做？如果某個工具損壞了要怎麼安裝？如果某些工具有升級版要怎麼做？……用許多可能會發生的”如果”來檢視沒有完整說明的產出，就會發現根本不知從哪裡著手。

最近看了一些不錯的文章都有提到知識管理的重要性（高績效研發管理實務運作／李紹榮、研發人員常見問題之剖析與探討／吳英秦），這幾年我也體認到經驗的保存是很重要的事。為了特定目的如何定義需要的物、做哪些事可以得到那些物、怎麼設定能讓那些物具備功能、怎麼使用那些物可以達到我們要的目的，每一個想法與實現都忠實地記錄並收集起來，就能讓原先沒有參與的人很快地建構起與自己相近的觀念與成果。

這個開發平台現在連我在內一共有三個人完整安裝過，但是每個人都花了不少時間去詢問與搜索，像我就在網路設定上花費一整天才弄妥。做出一個完整的開發平台需要做很多的動作才能達成，我偶而會想：倘使幾個月後需要三個人根據自己手邊的記錄重灌一次的話，我們各自會花多少時間？如果各自找一位其他的工程師看著留下的資料重做的話，又需要多久？會問多少個問題呢？

有些道路是經過多次的摸索與碰壁後才發現到的最佳捷徑，沒法留下快速通往終點的記錄只會讓日後想走同樣路的人重覆花費摸索與碰壁的時間，如果那條路需要多人次的進行時更是重覆地浪費資源。留下足以讓後人快速達到終點的作法，可說是犧牲自己時間換取節省眾人時間的一種高尚行為──這是近來瀏覽其他人在網路上提供安裝設定方式與心得時，我心中所懷的敬意。

X10 精確地拆解、完全地對應(2)──目標的解析

認為現有的文件寫得不理想時，總得說出比較理想的寫法才算是建設性的意見。依據前面同事留下來的資料重新安裝Java Power Tool中提到的工具時，一邊問他們當初沒有記錄下來的部分、一邊思索要用什麼樣的方式表達才能讓其他人全面地明瞭所做的一切，並且可以製作出同樣的結果。

今年撰寫的那份計畫書其實也是沒人想寫的那種，不過在構思的期間與大主管們有過多次的討論，學習開始去切割目標為多個小目標，再對每個小目標定義要做些什麼、要怎麼做等等的想法。我們認同程式碼品質這個無法直接度量的目標，可以用程式員日常工作的規範來間接證明，所以先列出程式員所有“與程式碼相關“的行為，根據每個程式員的行為定義相關的動作，再思考每個動作是否有適當的工具搭配以及操作的必要規範。


註：這只是大致上的示意圖，還不是完整的定義與對應。

這張圖是根據“程式碼品質”這個目標延展出來的四個群組：專案事件、程式員做的事、搭配工具與定義的規範，其間的每個項目都與緊鄰群組中的項目產生關聯。以往討論程式碼品質時都僅能就幾個點提出建議，但是參考Java Power Tool的內容卻可以就完整的面來探討：從專案與程式員個人事件發生的起點開始展開處理的流程與要做的動作，並針對每個動作找出最適合的工具來加快處理速度並減少錯誤，一步步使用規定的工具做完應做的事同時讓所有產出都通過檢查且符合規範。

針對一個較大的目標，完整地定義出點、線、面來全面涵括相關的事物，不是更容易規範出大多數人都能接受的標準嗎？

X09 精確地拆解、完全地對應(1)──遇到的現象

公司前陣子陸續驗收了幾個專案，主管利用可喘息的空檔重新思考如何確保程式碼的品質。品質，無法直接以數據衡量其好壞，因而參考Java Power Tools這本書中的工具與作法，同時決定沿用同事已經先行研究一陣子的產出再擴展下去。

同事的作法是使用虛擬機器安裝Ubuntu作業系統後加上需要的應用程式，雖然他同樣參考過那本書，但僅是在虛擬機器上裝好書上提到的軟體。我們拿到虛擬機器映像檔時真的是有點愣住，因為根本不知道軟體安裝的順序、方法與設定（他的說法是使用者只要有能用的東西就好，不用管怎麼安裝的），也不知道Programmer日常工作要在什麼時機、用什麼樣的方式來運用各個軟體（他有說了大概，但是沒有確實的工作流程）。

那時我還在別的專案忙著，主管先找了其他同事來幫忙弄清楚虛擬機器上的每個環節，同時希望他們能定義每個工具使用時的規範（例如Subversion在commit時說明的範本），當時也言明在完成後會由我根據產出的文件從頭到尾重做一次來檢驗結果。但是這幾天自己下去重頭做時才發現記錄的內容感覺很不齊全，很多地方不知道從哪裡開始、不確定要做些什麼、不知道做了之後改變了什麼。

工程師（指我遇到過的以及我自己）撰寫使用手冊與教學文件的產出普遍不理想，主要原因是對於撰寫這些文件的態度為“把自己完全清楚的東西全部寫一遍，只是浪費做其他事情的時間而已”，於是就以自己的角度思考寫出能回憶到的部分。在很多時候就因撰寫者與使用者的程度與觀念落差造成無效的文件。

Y09 關於共用核心元件（Core Component Library）

在因緣際會之下參加了經濟部標準檢驗局舉辦的Core Component Library（簡稱UN/CCL）座談會，才知道聯合國UNCEFACT已經提供一套方法，針對企業間電子商務行為關係將彼此的交易流程以共同同意之方式、順序及訊息格式進行整合。其範圍涵蓋了各行各業非常多的商業資訊物件，在最近的09A版本已經定義了五千多種。

UN/CCL主要的目的在於各國、各系統間的資料交換，翻閱過08A的中譯資料發現已經定義了許多曾經使用過的資料。席間有人發問說資訊物件內的欄位並沒有定義長度，學者回答資料若定義長度在語系轉換時會發生長度計算的問題，不過我認為資料在使用的意義上並沒有長度的規範，而是系統設計時因應儲存限制才加以規定的。

然而UN/CCL只是該組織計畫一部分，資料的定義用ebXML來描述，Business Process與Information Model會有UMM方法論，相對地這也是範圍更大、更難定義的部分。根據簡報的陳述，倘使各國的菁英最後能夠定義出絕大部分的商業流程與其對應使用的商業資訊物件，未來的電子商務相關系統開發模式很可能是：

●定義使用系統的所有Actor
●定義每個Actor所使用的Business Use Case（從清單中勾選）
●定義每個Business Use Case裡所需要的Business Process（從清單中勾選）
●定義Business Use Case裡的Business Process執行順序
●定義Business Process對應的CCL資料物件中的使用資料欄位（從清單中勾選）
●底層的架構會根據勾選的資料物件欄位產出ebXML傳送到另一端的系統

這個組織已經運作好幾年，但是以“Core Component Library”搜尋中文網頁時所得的資訊並不多。從另一個方面來看，自己定義的“人－事－物”關係能夠接近許多專家定義的“Actor－Business Process－Core Bomponent Library”精神時，總是對自我更多了幾分認同。

官方公佈UN/CCL版本的網址是 http://www.unece.org/cefact/codesfortrade/unccl/CCL_index.htm。

X08 批評學生不敬業的事件

原始網頁：http://parenting.cw.com.tw/web/docDetail.do?docId=1844
學生回應：http://www.udn.com/2009/11/10/NEWS/OPINION/X1/5242253.shtml

聯合新聞網上刊登了這個事件，洪蘭小姐在訪視台大醫學院時對學生們上課表現出來的態度不以為然，在天下雜誌發表「不想讀，就讓給別人吧」一文，對此事件，台大醫學系系學會會長在新聞網的專題裡回應了一篇文章說明。我當然不懂學醫的人求學時會發生什麼事，不過我對每個人在不同情境下的思考邏輯很有興趣，所以順便探索一下。

洪蘭小姐的立場很簡單，她認為在求學時期應該對所有學校相關的事（包括與求學無關的）都應抱持負責的態度，更何況那是上課時間；學生的回應也很簡單，表面上承認態度的確有所不當，不過那些都是因為有更正當的理由才會造成那些現象的發生，如果在專業方面能有所表現的話應能體諒其他不拘小節的行為。

在許多人的觀念裡資訊人員是不拘小節的族群，以往的我就是落在這個集合裡，認為只要我能夠完成公司交付的所有任務就算是達成工作目標，平時上班穿著牛仔褲、涼鞋也不以為意。十年前應徵現在的工作被錄取時，詢問上班應該如何穿著，那時的Ｊ主管說：“你希望別人怎麼看你就怎麼穿”。從那天起，我每天都穿著長袖襯衫、西裝褲與皮鞋，因為我認同穿著可以反應出一個人的內心。我們在開會因為都帶著電腦，有時總會分心做些與當時會議無關的事，Ｊ主管有次生氣地說：“我放下手邊的工作專心地與各位開會，如果大家沒法付出與我相等的專心，我現在就離開“，自此之後我也不曾在會議上別其他事情。

我沒法認同學生的辯詞，因為我體認到在不同的情境下人都應該做該情境下應做的事，每個情境都是獨立存在的，不該拿其他情境的影響來解釋現在的錯誤。上課是學生與老師的互動，老師全心講課時，下面的學生付出了多少？相對地學生想來認真聽課時，敷衍的老師同樣對不起學生。上課會打瞌睡只是證明睡眠真的不夠，如果睡得夠的話看到看過的電影會拿起別的書來看；上課會吃便當只是證明不想犧牲吃的享受，如果時間真的不夠會寧願買個飯糰在休息時間隨便吃吃也不會想在課堂上分心。

在上課的態度不佳是事實，沒去承諾去努力改善這個現象，卻試圖用所有學生的“全”讓那些學生成為“偏”、用專業課程為重的“全”讓通識課程成為不重要的“偏”。一個小故事裡的壽司師傅在捏了上千個壽司後已經累了，仍同樣專心地製作壽司給關門前最後一位不重要的客人吃，旁邊的師傅說你已經很累了不如隨便應付一下，他正色道：“這個壽司只是我今天所做的千分之一，但對這位客人來說卻是他的全部。如果隨便做做，客人就會認為我做的壽司就是這麼爛！”

在想要合理解釋自己有問題的行為前，是否思考過洪蘭小姐所訪視的那一堂課就是她所看到的全部呢？

註：在電子工廠上班的朋友說，每批產品都會抽檢一定比例的樣品，只要其中一個有任何一個錯誤就會將整批產品重新作測試。每個人都可以決定要用什麼樣的標準來檢視自己！