關於線上文檔製作工具與管理相關機制摘記

目的:可便於在線上製作與編輯主控性文件 (具有大綱架構 (章、節)的 TOC (Table of Contents)文檔)。除了提供 HTML 格式的瀏覽,也可以轉換格式為 PDF, ePub/Mobi 等適於實體印刷與電子書格式。整理後的文檔可以容易上傳至 Hosting Server (網站/雲端空間),甚能具有版本控管與協同編輯撰寫的功能。

說明:原來為編寫 Python 線上文件而所開發以 Python 語言編寫的工具-Sphinx,已逐漸成為製作線上文件的最普及好用的免費開源工具。關於 Sphnix 的幾個主要特性:

  • 輸出格式:HTML (including Windows HTML Help), LaTeX (for printable PDF versions), Texinfo, manual pages, plain text。
  • 廣泛的交互參考 (cross-references):語義化的標記 (semantic markup),並對包括 函式、類別、引用文、術語詞彙表與類似片段資訊提供自動化的鏈接 (automatic links)。
  • 階層式的結構: 可輕鬆定義樹狀文件,並自動化鏈接同級/父級/下級 (siblings, parents and children)的文件。
  • 自動化的目錄: 產出與特定語言關聯的模組索引目錄。
  • 程式碼的處理:利用 Pygments highlighter 自動生成各程式語言的高亮度代碼區塊。
  • 擴展套件: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs) ...。

先瞧瞧一位大陸知名 IT 作者利用 Sphinx 所整理出很棒的線上文檔-GotGitHub,就可以看出 Sphinx 的強大功能。

另外一個參考展示-編寫《Redis 設計與實現》時用到的工具

閱讀全文 »

[備註] 安裝與整合 xUnit 測試框架@VS2012

開發環境:Visual Studio 2012, Update 1 (必須)。

說明:VS2012 已整合各測試框架的 Test Runner,包括 NUnit, xUnit 等。藉由標準的介面,可讓各類測試框架於 VS2012 內的 Test Explorer 歸納測試方法 (methods),並執行測試、瀏覽測試結果。

xUnit 可說是繼老牌 NUnit 的後起之秀。關於兩者之間的比較,可參考-xuint和其他的單元測試框架的比較。個人尤為欣賞 xUnit 的 DDT (Data Driven Test)的機制-Theory,可參考這一篇-xUnit Theory, the Data Driven Unit Test

xUnit Theory 可讓測試方法具有參數 (parameters),而能接收多個資料來源 (InlineData, PropertyData, ClassData, ExcelData, OleDB/Sql ServerData)的資料輸入,讓測試機制更能充分利用測試數據。一個 Theory 可參考如下的寫法。

 1: [Theory]
 2: [InlineData(1, 2, 3)]
 3: [InlineData(3, 4, 7)]
 4: [InlineData(30, 10, 40)]
 5: public void Add_AddDataValues_ReturnsExpectedResult(int first, int second, int expected)
 6: {
 7:     var actualResult = Calculator.Add(first, second);
 8:  
 9:     Assert.Equal(expected, actualResult);
10: }

安裝:兩個 xUnit 套件是必要安裝的 (全於 VS2012 內安裝)。

  1. xUnit.net runner for Visual Studio 2012 extension
  2. 利用 NuGet 安裝 xUnit.NET。

閱讀全文 »

淺論中小型專案版控系統的基本分支(branch)規劃

關於版控的分支與標籤的基本觀念,可參考原來寫的一篇:關於版本控管系統的分支(branch)與標籤(tag)的區別

關於中小型專案規模的版控分支 (branch)規劃,個人以為應該至少有三條 (以 Git 為例):master, develop , issue。

master (主幹):作為對外版本的釋出 (release)。

develop (開發用分支):作為內部開發的主要分支。其內的開發版本並不會對外釋出。

issue (支援性分支):Bug/Hot-fix (臭蟲/重大更新), 新功能 (new feature) ...。一般紀錄於「Issue Tracking」系統內的 問題/功能 等待解決的 Issue,即會轉入該分支。

看圖說故事

中小型專案規模的版控分支規劃
(點擊圖片鏈接看原圖)圖、中小型專案規模的版控分支規劃

閱讀全文 »

關於版本控管系統的分支(branch)與標籤(tag)的區別

版本控管系統:版本控管係為「建構管理 (configuration management)」的範疇。理論上,關於「分支 (branch)」與「標籤 (tag)」,從觀念上來看在各版控系統應是類似的,只是做法不同罷了。

Suversion vs. Git:雖然兩者常被拿來比較的是,subversion 是集中式的儲庫 (repository),而 Git 則為分散式的。但若從專案管理者的角度來看,要管理的其實只有一個:位於伺服器上的儲庫。即使如 Git 可以有一堆分散式的儲庫,但管理者真正只有管理到例如儲存在 GitHub (or private Git server)上的儲庫。至於開發者在私人的儲庫內,要如何分支與標籤是自己的事,只要最終能提交給專案管理者做合併 (merge)即可。

關於版本控管的分支與標籤說明範例
(點擊圖片鏈接看原圖)圖、關於版本控管的分支與標籤說明範例

    關於分支 (branch):

  • 原則上,任一版本管控系統只有一條主幹,例如 suversion 稱為 trunk,Git 稱為 master。
  • 每一次對開發文件的提交 (commit),可視為是一個節點 (node)。節點會持續隨開發時間推進,並期能達成所設定的里程碑 (milestone)。
  • 如果把主幹的任一節點當成是可能對外發布的釋出 (release),而這些釋出不希望與開發/維護期間的文件相互干擾,則可以另闢其它分支 (branch),可與主幹並行開發並個別維護。主幹與分支(可能多個)盡量將耦合性 (coupling)降低,讓版本釋出與開發維護得以順暢並行。
  • 分支後的開發/維護的節點,最終仍需將修改的文件回到主幹上,此時就必須做「合併 (merge)」的動作。

閱讀全文 »

[研討會-免費] EA UML 開發工具新功能剖析與應用 (12/15)

報名與詳細講座資訊請至:
http://www.hsdc.com.tw/courses/ea10_new_features_seminar_20121205

 o 報名費用:無。但須自付咖啡或茶等飲品自費 (最低消費 NT$150)
 o 日期:2012/12/15 (星期六) PM13:20 ~ PM 17:00
 o 地點:加爾第咖啡莊敬店。北市信義區吳興街269巷1弄21號
  電話:(02) 2345-1136
  http://kaldi-coffee.com.tw/mainwebsite/about4_a.html
 o 報名人數名額:22人。
***
請注意,由於場地限制,需要保留及計算報名學員們的座位,請確定會前來參加後才填寫報名單,若不克前來,也請於報名表單或來信取消報名。
——————————————————————————–
§講座主題:EA UML 開發工具新功能研討與應用

第一場、主題:EA 10.0新功能大剖析
  1. 加強的Document產生器
  (1) EA的Master Document進階應用
  (2) 利用Custom SQL進行文件客製化
  2. 程式碼支援加強版
  (1) 利用HSDc Sequence Plugin與EA的除錯Sequence產生器進行程式碼健診
  (2) 支援Android的除錯與執行
  (3) 利用State Machine + Java Script 模擬UI操作
  3. 其他更方便的操作

閱讀全文 »

[轉貼] EA 與 Visio UML 工具比較

這一份 EA (Enterprise Architect) 與 Visio 的比較表,是由我們 HSDc. Cathy 小姐找了許多資料,用心所整理出來的功能比較表。

EA 怎麼會與 Visio 來作比較? 其實這是國內某大銀行 IT高級主管所要求的,必須附在產品採購內的評估報告。

一開始的直覺是,這兩樣能作比較嗎? Visio 算是一種繪圖製作的工具,提供了諸多各類型,包括網路、基本流程、甘特圖、乃至於 Mindmap, UML 等圖形元件 (Widgets)的模版 (Template):而 EA 則當然是 UML 專業設計的工具。

但是,我還真問了許多已經使用過這類如 EA, RSA (Rational Software Architect), Together 等工具的軟體開發者 (Developer),到底與 Visio 的主要差異為何,沒想到絕大部分還真回答不出來,以為就是在繪製 UML 圖形的便利性與否而已。

不然! 其實以 EA 這等專業 UML 工具,為何售價需要近萬元? 必然是有 Visio、或者一般免費 UML 工具所無法比擬的特點。但可不是繪圖容易與否這類問題上,真正的主要差異在於:

  • 有效調和專案 (Project)開發過程中,不同角色 (Role)的開發者所設計出來的 UML 產出 (Artifacts),並在這些產出之間,有效監控並期能保持一致性。

更簡而言之來說,當專案是需要團隊協同開發時,則專業性的 UML 工具則是有其必要的,且更能有效保存軟體開發過程中的設計產出,成為團隊甚或企業的有效資產。

至於 EA 與 Visio 兩者的ㄧ些主要功能差異,則可以參考底下 Cathy 小姐所整理出來的比較表:

閱讀全文 »

軟體思維顧問

專職軟體輔導與教育訓練的獨立顧問。輔導企業資訊單位如何有效組織系統開發與維護;輔導開發人員達成有效的專業分工。傳授如何把軟體作軟 (Keeping Software Soft)的技能,得以提昇系統的彈性/延展,並進而創造系統的再利用價值。

Personal