快看，我的代碼能“自己說話”！
開發人員什么時候最崩潰？
別人我不知道，就我而言，要是我耗費了幾個小時來研究代碼，試圖破譯它的目的，卻遲遲不得門路，真是恨不得找到寫代碼的那個家伙，讓他回爐重造。
今天我們將在這篇文章中探討如何編寫自文檔化的代碼，讓代碼自己會說話。
什么是自文檔化的代碼？
自文檔化的代碼是以清晰、富有表現力的方式編寫的代碼，無需大量的注釋和外部文檔，就能讓人理解代碼的目的和功能。
自文檔化代碼的特點：
- 可讀性：代碼易于閱讀和理解，一目了然
- 富有表現力：清楚傳達代碼的意圖和目的
- 可維護：代碼易于修改和更新，不會引入錯誤和重大更改
自文檔化代碼的重要性
編寫自文檔化代碼的好處：
- 開發人員可以快速掌握代碼的目的和功能，減少理解和使用代碼庫所需的腦力勞動。
- 新的團隊成員可以更快地上手，因為他們不需要特別依賴外部文檔。
- 最大限度地減少團隊成員之間的誤解，促進對代碼庫的共同理解。
- 即使隨著時間的推移，維護和更新也依然方便簡單，因為開發人員可以快速理解現有代碼并做出明智的更改。
如何編寫自文檔化的代碼
了解了什么樣的代碼是自文檔化的代碼之后，敲黑板，我們的重點來了，那么，怎么編寫這樣可以“自己說話”的代碼呢？
1.使用有意義的名字
使代碼自文檔化的最有效方法之一是對變量、函數、類和模塊使用有意義的名稱。
請看以下示例：
// Bad
const x = 5;
const y = 10;
const z = x + y;
// Good
const numberOfItems = 5;
const itemPrice = 10;
const totalCost = numberOfItems * itemPrice;在Good示例中，變量名稱numberOfItems、itemPrice、totalCost清楚地傳達了用途，理解起來非常方便。
2. 編寫小而精的函數
編寫小而精的函數是自文檔化代碼的另一個關鍵。函數應當功能單一，并準確命名以反映其目的。
例如：
// Bad
function processData(data: any): any {
// ...
// Lots of complex logic
// ...
return result;
}
// Good
function extractRelevantFields(data: Record<string, any>): Record<string, any> {
// ...
return relevantFields;
}
function applyBusinessRules(relevantFields: Record<string, any>): Record<string, any> {
// ...
return processedData;
}
function formatOutput(processedData: Record<string, any>): string {
// ...
return formattedResult;
}通過將大函數分解為名稱更具描述性的小而精函數，代碼明顯更可讀了。
3. 使用描述性的函數名稱和方法名稱
在命名函數和方法時，使用描述性的名稱可以更加清楚地傳達其目的和操作。注意：應盡量避免使用通用名稱，如handle()或process()這樣的寫法。
請看示例：
// Bad
function handleInput(input: string): void {
// ...
}
// Good
function validateUserCredentials(username: string, password: string): boolean {
// ...
}看到了嗎？描述性名稱validateUserCredentials清楚地表明了函數的作用。現在，我們哪還需要額外的注釋？
4. 利用 TypeScript 的類型系統
TypeScript 強大的類型系統可以大大增強代碼的自文檔化。所以要懂得利用工具，借助 TypeScript 的功能，使代碼更具表現力，及早發現潛在的錯誤。
例如：
- 接口和類型：使用接口和自定義類型來定義數據結構的形狀。
interface User {
id: number;
name: string;
email: string;
}
function getUserById(id: number): User | undefined {
// ...
}- 枚舉：利用枚舉來表示一組固定的值，提供了一種清晰易讀的方式來處理不同的方案。
enum PaymentStatus {
Pending = 'pending',
Completed = 'completed',
Failed = 'failed',
}
function processPayment(status: PaymentStatus): void {
// ...
}- 類型推斷：盡量使用 TypeScript 推斷類型，因為可以精簡代碼。
// Bad
const count: number = 10;
const message: string = 'Hello, world!';
// Good
const count = 10;
const message = 'Hello, world!';5. 使用強類型 ID
在 TypeScript 中處理 ID 時，建議使用強類型 ID，不要直接上字符串和數字。強類型 ID 提供了額外的類型安全性。
實現強類型 ID 的一種方法是使用不透明的類型：
// user.ts
export type UserId = string & { readonly __brand: unique symbol };
export function createUserId(id: string): UserId {
return id as UserId;
}
// post.ts
export type PostId = string & { readonly __brand: unique symbol };
export function createPostId(id: string): PostId {
return id as PostId;
}這里我們使用強類型 ID，確保了UserId只分配給需要UserId的屬性和函數，PostId只分配給需要PostId的屬性和函數。
function getUserById(userId: UserId): User | undefined {
// ...
}
const userId = createUserId('user-123');
const postId = createPostId('post-456');
getUserById(userId); // No error
getUserById(postId); // Error: Argument of type 'PostId' is not assignable to parameter of type 'UserId'.強類型的 ID 有助于在編譯時捕獲潛在錯誤，使代碼更具表現力和自文檔化。
但是，與使用簡單的字符串類型相比，強類型 ID確實會引入一些開銷。所以我們需要根據項目的需求和規模權衡利弊。
6. 增強團隊凝聚力
團隊工作的時候，建立一致性至關重要，不然你有你的標準，我有我的約定，程序還怎么跑得起來？
關于一致性，有一個非常重要的方面是命名約定。最好的做法是建立一個風格指南，定義變量、函數、類和其他實體的命名方式。
例如，可以使用類似這樣的術語：
- get：檢索 API 或數據源中的單個值。
- list：檢索 API 或數據源中的一組值。
- patch：部分更新現有實體和對象。
- upsert：更新現有實體，如果不存在，則插入新實體。
統一執行術語可以確保整個代碼庫的一致性。
例如：
function getUser(userId: UserId): Promise<User> {
// ...
}
function listUsers(): Promise<User[]> {
// ...
}
function patchUser(userId: UserId, updatedData: Partial<User>): Promise<User> {
// ...
}怎么樣，是不是明顯更易于大家理解了呢。
除了命名約定之外，還可以為代碼庫的其他方面制定準則，例如文件和文件夾結構、注釋、錯誤處理、測試和代碼格式等。
在團隊中工作時，我們有時候可能不習慣或者不贊同正在執行的某個約定。但是，重要的是要記住，一致性和協作對于項目的成功至關重要。
即使你有不同的偏好或編碼風格，也應該遵守約定。從而保持一個有凝聚力的代碼庫，減少混淆。
7. 復雜場景使用 JSDoc 或 TSDoc
雖然自文檔化的代碼非常優秀，但是不可否認的是，在某些情況下該上文檔就得上文檔，例如如果遇到復雜的算法和復雜的業務邏輯，你不寫注釋，簡直就不給后來人活路。
在這種情況下，可以考慮使用 JSDoc 或 TSDoc 來提供清晰簡潔的文檔。
/**
* Calculates the Fibonacci number at the given position.
*
* @param {number} position - The position of the Fibonacci number to calculate.
* @returns {number} The Fibonacci number at the specified position.
*/
function fibonacci(position: number): number {
if (position <= 1) {
return position;
}
return fibonacci(position - 1) + fibonacci(position - 2);
}通過 JSDoc 或 TSDoc，我們可以為復雜的代碼提供額外的上下文和說明，而不會使代碼庫變得亂糟糟。
結論
編寫自文檔化的代碼是每個開發人員都應該努力掌握的一門藝術。
通過有意義的名稱、小而精的函數、 TypeScript 的類型系統以及明智地使用文檔，我們可以創建可讀的、富有表現力的和可維護的代碼。
自文檔化的代碼，可以減少對外部文檔的依賴，使我們的開發工作更輕松。
所以，下次寫代碼的時候，花點時間考慮如何使其更具自文檔性。相信我，未來的你自己和隊友都會感謝你！聽我說，謝謝你，因為有你，溫暖了四季。
