Gelis 技術隨筆-部落格

淺談 Code-Review 前言 最近，有些朋友也在談論 Code-Review 以及 Code-Review 所遭遇到的困難等，今天我就來談談我自己對 Code-Review 的一些初淺的看法。 近年來我在各中小型企業執行顧問工作，有 API Framework 客製化的框架開發、也有 Redis 導入工作、也有日常維護（專案開發技術顧問角色/Trouble-Shooting/專案軟體架構設計角色/單元測試顧問/教育訓練.../etc），而不管我執行哪一種工作，協助解決 Bug 也好，很多時候的第一件事就是與該團隊成員一起 Code-Review，先來看看程式碼，了解出現問題的 Source Code，這是再稀鬆平常不過的事情了，今天，我就來分享我在各大企業，許多團隊實際進行顧問時的 Code-Review 所看到的一些現象，並分享給各位。 實務上 Code-Review 以我個人的經驗我覺得可以區分為以下兩種： 非正式的 Code-Review： 什麼叫做『非正式的 Code-Review』呢？以往，我在帶團隊做專案時，不管是我與同仁 pair-programming 時，或者相互討論需求時，我們會同時進行 Code-Review，這時你會說這也算？對!!! 我認為，當然算，當然有些決議會記錄下來在下一次正式討論時與團隊同步，但是我個人非常重視這個過程，而且這些討論一樣是在『有團隊開發共同規範的基礎下』進行的。這些通常在位子上就可以進行。 非正式的 Code-Review 其實也有己的進入點（其實非正式場合我不建議用 Code-Review 做為內容表達方式，一來讓人覺得它就是要來噹我的會議、二來就是有犯了什麼錯，所以準備被指正等。） 1). 當 Junior 工程師對需求有問題時  2). 當 Commit 的 Source 或 Pull 下來的 Source 有問題時  3). Merge 出錯時 以上 3). 點我統一說明，非正式場合不建議大費周章發會議通知 + 找所有人一起參與，一來花費過多時間也沒有效率，專案開發是分秒必爭的，本來就不建議有過多的浪費（敏捷也告訴我們要減少浪費）使用最少的資源，與該需求相關人等討論即可，甚至在位子上花 10-20 分即可進行，我個人是建議不要超過 30 分鐘。 Merge 出錯通...

軟體架構設計：有『題』（二）- 為X宏網路售票系統加入 API First 網站 前言 在上一篇文章〔 軟體架構設計：有『題』- API 設計原則以『線上售票系統為例 〕裡面，我們幾乎在 LINQPad 上完成了一個線上購票的雛形，而這一次，一個部分是我們會再持續的建模的過程中補足一些上一次的缺失部分、第二部分則是加入網站設計部分，而這個網站會使用先前我在某客戶端所開發的 API Framework 框架為基底來設計，除了完全支援 >NET 6 外，這個框架封裝的許多在 Clean Architecture 裡屬於 Infrastructure 的部分，包括 【Role Security Access Controll Layer】與【Notification】以及【Log】等功能，更細部的部份我們下面再來談。 持續的建模 針對上一次，我們在X宏網路售票系統中用 UML 所呈現的 DDD 的 Domain Modeling 與 對照 Scenario 可以發現幾個小缺失。 (1). 加入 ShowTime 的 ValueObject (2). 建立 SeatReservation 實體的 Create 方法 (3). 調整 ConcertVenue 音樂會場地物件實作 另外，也針對 Application Services 的 購票作業 Reservation 方法調整程式碼邏輯，因應票卷 Ticket 由 Ticket.Create 方法來產生，並需要傳入（訂位代號：ReserveID; 場次：ShowTime） 程式碼中使用的術語，完全參照 Domain Modeling 與 事件風暴 中所精練出的通用語言 (Ubiquotius Language)，以確保程式碼完全可以對照領域模型，建模的過程也完全可以撰寫程式碼，並確保在最短的週期裡完成程式碼的設計與修改。 程式碼調整如下： Domain Layer 的程式碼 public interface IAggregateRoot { } public class Entity { } public abstract class ValueObject { } // 票卷實體 public class Ticket: Entity, IAggregateRoot { ...

軟體架構設計：有『題』- API 設計原則以『線上售票系統為例』 前言 先前，我有篇文章是以讀過【Get Your Hands Dirty on Clean Archiecture】後的心得感想，這本書的中文名稱是：【Clean Architecture 實作篇：在整潔架構上弄髒你的手】，讀完這本書大約是去年 2022/10 月左右，也是我當時在開發 API 新版框架大爆發的時候，書中給我不少的啟發，在配合實際的專案開發的實作經驗 + 框架設計所需要的框架設計便引入六角架構的設計方式，藉以改良原有的舊版的框架，而這篇『 軟體架構設計：無題 ( http://gelis-dotnet.blogspot.com/2022/08/blog-post.html )』中便是以完整的〔六角架構 (Hexagonal Architecture)〕並加以解釋如何在六角架構中落實單元測試 Unit Test，這些都是我讀完書後，實際落實在專案上的實際做法 + 分享。 當時的六角架構 + Unit Test 的範例程式在這： https://github.com/wugelis/AdapterInOutLayerSapmle 上次是無題，今天，我以一個X宏線上售票系統為例子，我們從頭到尾地的，Step By Step 的來介紹，這個 API 售票系統的建置過程，而這裡，我也會搭配 『API 設計原則』一書裡的一些做法，也就是說，這裡開發的 API 會使用 API First 的設計樣式，因為這裡的 API 設計的出發點為該企業、在這個商業模式上所能夠提供之『商業能力』回出發點考量，而不是過往傳統的單一客戶(UI)思維的客製化模式考量，所謂的 API First 是轉向為產品化思惟的導向模式，如此也才能發揮 API 在市場上的價值，這也才是 API First 的思維模式。 需求來源 圖（一）、線上售票系統需求 今天的需求來源，是一個線上售票系統，先前我曾在專案中製作過一個售票系統的雛形，這裡我就拿這個範例來以 DDD 來進行戰略建模，並搭配使用我在新竹顧問時所開發的新版 API Framework 來實作並支撐這個售票系統 API 的 Infrastructure Layer，沒錯，所以言下之意，我們以 DDD 來驅動這個售票系統 API 的開發，所以這裡的 Core...

為什麼開發人員總是會產生過度設計的程式碼？ 問題的來源 什麼是過度設計？開發人員為什麼會過度設計？過度設計與預先設計有什麼關係？過度設計是最終導致的結果，而預先設計無非是想讓軟體的程式碼撰寫落在刀口上，減少時間的支出來產生可交付的程式碼。但是這件事情好像沒這麼簡單？即便談需求的是我，我還是會有過度設計的程式碼產生，為什麼回如此呢？但這樣真的完全不好嗎？ 會產生過度設計可能有以下幾個原因。 分析時間過久 以前筆者曾提過傳統的瀑布式容易造成分析時間過長，最終就導致過度的設計而不自知，撰寫程式碼時因為關起門來寫，一些就是 3 個月或半年，脫節的需求產出的程式碼可能大部分不是客戶要的，這也是種過度設計，只是大部分設計出不正確的程式碼。 這會產生比較嚴重的反效果，一個是因為需求的脫節，即便抓回方向，但錯誤的設計已經使系統長歪，要修復往往非常的耗時耗力，甚至打掉重練比較快的情況也可能發生。 搞不清楚客戶說什麼 所謂隔行如隔山，軟體公司常只接針對特定領域的專案，或熟悉的領域進行客製化，好比筆者10幾年前曾待過專接流通業的 SI 公司，突然接金融電信領域的專案通常前 1-2 個失敗機率極高，為什麼，因為不熟悉這個產業的通用語言。然而這樣的接案就是極高的風險，筆者甚至分享以前遭遇到的經驗，曾經有同行求救於我們公司，他們因為不熟悉該領域硬是接下後無法收尾，而求助於我們公司熟悉金融領域的部門，當然，最後我們也沒有答應協助收這個爛攤子。 所以，Gelis 認為，搞清楚客戶說什麼常重要，在三地確認客戶腦袋的想法也很種要。 需求不明確 有可能需求訪談客戶主事者不在，或者具備決定權剛好不在、又或者客戶因為處於新員交接、正在熟悉此業務，所提需求自然諸多漏洞 + 沒想清楚。這筆者就曾遇過客戶端兩位經理在訪談會議時爭吵需求執行內容，讓在場的廠商非常傻眼，很想請他們去廁所打一架看誰贏了，我就做哪一個需求。 或者純粹是使用者想太多，想變更需求。或者自己搞不懂自己想要什麼，這比較常見。 也有可能開發團隊最後自己腦補，產生了一些設計，結果最後又不同於客戶確認的規格內容，這也是種過度設計，因為你設計了一堆不需要的架構內容。 如此一來，程式碼修修改改，不產生技術債都難。 保留設計 這接續前面的需求不明確，就因為需求不明確，所以開發人員就做了許多『預先設計』的保留，...

軟體架構設計：API 設計準則（一）、API 的設計開發與挑戰 前言 最近因緣際會地接下了一門課，這門課是要講授關於 API 開發與設計原則和最佳實踐等相關的內容，雖然我不是第一次接觸這個主題，也曾開發過 2 個 Web API Framework 框架 (以下的 API 均代表 Web API)，只不過，這企業內部 API 開發框架，我們大部分以專案開發的角度來看 API 與 傳統 SPA 前後台網站設計與開發的角度在看每一件事情：像是（分析=>設計=>開發=>測試=>佈署..等）這是大部分開發者熟的純軟體工程，但是切換到 API 的思維會有些不同，這倒也不是說原有的軟體工程不管用，API 依舊是軟體開發出來的，但是整個軟體生態的改變會間接 或者 直接影響軟體服務之間『操作』或『取得』其他服務的方式，尤其在 Cloud 應用與移動裝置的應用會更加的劇烈，一個裝置使用一個公開的第三方服務已經是一個很常見的應用場景 （比如：比如物流商與超商之間 API 的對接、線上售票系統與 iBon 之間的對接、或者代收服務等，這些都是 API 跨領域對接最典型的服務） ，而這邊會談到的是更多直接是以 API 交付出來的雲端服務 Cloud Services、甚至是企業端的平台服務等。 傳統的軟體開發切換到 API 的設計與開發會有那些挑戰？這些我們等一下談。 從軟體工程切換至 API 開發的挑戰 我們常見的軟體工程，不外乎圍繞著專案開發 或 產品開發，這些軟體的終端使用者大都是『人』會會有人機介面，所以不管你是推行 Agile 的軟體開發或是 Kanban 或是 Scrum，我們的最終目標可能都還是完成哪個業務單位『人』想要的『（東西 / 產品）』或者是『市場』（可能）需要的產品。 切換到 APIs 變成 API 與 APIs 協作溝通形成一個最佳的實踐、或 Solutions，你的系統也許是第三方的 API 服務提供者；也許是你也是 GCP/Azure/AWS 等 Cloud 供應商的用戶端，你的軟體系統也是由多個 APIs 所組合而成的 "大系統"，這些 APIs 之間有幾個首要的幾個挑戰要先解決。 (1). 對通訊協定的選擇 也就是像是 HTTP/gRPC/MQTT.. 等等，通訊協定是 APIs 彼此之間溝通的...

SA (System Analysis) 與軟體架構師的差別？ 前言 這其實是先前在臉書回復其他社團的貼文，為避免當時的內容與想法被臉書淹沒，於是將其整理成文章，表示我沒有將臉書當成文章在寫。 雖然現在流行 AI 撰寫文章，但我可以證明本文章絕對不是 ChatGTP 撰寫的，內容與想法 + 圖片都是出自我的想法 與 工作相關經驗。 版篇文章以台灣軟體產業為基準，不適用於歐美國家。 SA 與 BA 角色 也有朋友提到 BA 這個角色，其實我當時所處年代 (約西元 2000 年左右)還不盛行 BA (Business Analysis) 這個角色，尤其在台灣。其實在灣大部分一人分飾多角，像我現在同時是架構師、顧問、Traniner、有時是 Developer，有時也協助制定或定義開發（流程 / 規範）等等。 我認為 BA 的角色若相較於 SA 更為狹隘點（就軟體開發來說 / 或者說目的不同），怎麼說呢？一般軟體開發還是重在最後產出『成品/Product』、但 BA 並不是，他更著重在商業、滿足的所謂的『業務成果』，這又讓我想起 POPIT 模型，有興趣可參考附件連結。 SA 系統分析師 vs. 軟體架構師 的差別？ 回歸到主題，究竟 SA 與 架構師 的差別是什麼？ 我覺得差別蠻大的，是職能與本質上的差別。 架構師的職能更廣、而 SA 通常較為狹隘（了解商業需求／有的 SA 要為使用者需求負責） 12年前我是某家 SI 公司的 SA & 2010~2014 擔任軟體架構師的感想。 我畫張簡圖，即上方的 Logo 圖，簡要說明這兩者職能上的差別，越往（左邊是更懂技術 / 右邊更趨近商業流程）：  (1). 我認為架構師更全能、甚至含括 SA 的範圍。  (2). 許多軟體公司的 SA 是不碰技術的，頂多繪製 ER-Model  (3). 甚至許多軟體公司 SA 不是技術出身 結論： 因為軟體架構師在分析系統架構時，同時得要考量商業需求，並在軟體架構中落實， 套用先前敏捷的軟體架構， 除了不做（過多 / 過度）的設計之外，還要讓系統保持高度彈性 、 要因應需求、也要因應客戶端的環境、考量 Cost 成本問題、又同時得要考量團隊的 Skill，不是一窩蜂的導入新技術，在專案中， 任何技術的使用都需要 成本 的 ，軟體...

常見的程式碼壞味道（Code Smell or Bad Smell） 圖片取自：https://www.slideshare.net/ElMahdiBenzekri/art-of-refactoring-code-smells-and-microservices-antipatterns 前言 究竟重複的程式碼要不要共用它？傳統的軟體開發上，重複的程式碼幾乎被視為罪惡的來源，但是它真的有多可怕？ 常見的 Code Smells The Dispensable （一些可有可無的） Lazy Class (冗員類別） 如果一個類很少使用它會增加代碼庫的複雜性，從而阻礙開發。這樣的類可能是不必要的，它的功能可以成為另一個類的一部分。 Data Class (只有資料的類別） 一個類別只有包含『資料』未包含Methods，也就是說並未包含行為，不具行為模式的類別代表該『實例』容易被【其他類別所操控】。 Duplicate Code (重複的程式碼) 如描述，這也是上次有分享在我的 FB 社團 軟體開發之路［德國資深架構師給新手的建議］ 中有產生非常熱烈討論，這在社團朋友提醒下想起 Refactor 重構一書裡曾提過 rule of three 法則， 這個法則的定義是這樣的，有時部分程式碼重複其實是允許的（不是說重複一定是是被允許的）而是在某些 Context 情境下，該程式碼有一段時間不會衍伸別的功能 或 需求一段時間不會異動、且如要將它 DRY 會產生的『複雜度』或『花費時間』遠高於預估的時間 或 不值得在目前這個專案的節骨眼上花費這個時間來做這件事，加上它 DRY 產生的複雜度偶後產生的維護成本【遠高於】不 DRY 的情況下的維護本，那麼，在這個時候，這個異動頻率【極低】的程式碼就不需要花費這個時間來 DRY 了！！ 因為重點在於，重構是需要『成本』的。(迷之音：DRY 是種抽象化阿~😎) 這讓我想起之前，大約在 2016 年左右，在 101 的樓上某金融業客戶，曾經做過一個專案，這個專案就是因為客戶 DMZ 環境的因素，我讓內網的 Webside 與 DMZ 的網站保留了部分重複的程式碼，因為這段程式碼終年不需要異動，我也懶得花這個時間，而我居然也忘了這記件事情了.. 哈哈 Orz 不過原歸正傳，我個人還是認為，其實適當...