《英雄聯(lián)盟》夏季賽總決賽今日開打！JDG對陣LNG首發(fā)名單來了 Knight：準備三連冠
8月5日消息，今日17:00，《英雄聯(lián)盟》2023LPL夏季賽總決賽將正式開打，由JDG對陣LNG。對兩支隊伍來說，這場比賽不僅要爭奪夏季賽冠軍，更要決定誰才是LPL賽區(qū)一
開發(fā)人員什么時候最崩潰？
別人我不知道，就我而言，要是我耗費了幾個小時來研究代碼，試圖破譯它的目的，卻遲遲不得門路，真是恨不得找到寫代碼的那個家伙，讓他回爐重造。
今天我們將在這篇文章中探討如何編寫自文檔化的代碼，讓代碼自己會說話。
自文檔化的代碼是以清晰、富有表現(xiàn)力的方式編寫的代碼，無需大量的注釋和外部文檔，就能讓人理解代碼的目的和功能。
編寫自文檔化代碼的好處：
了解了什么樣的代碼是自文檔化的代碼之后，敲黑板，我們的重點來了，那么，怎么編寫這樣可以“自己說話”的代碼呢？
使代碼自文檔化的最有效方法之一是對變量、函數(shù)、類和模塊使用有意義的名稱。
請看以下示例：
// Badconst x = 5;const y = 10;const z = x + y;// Goodconst numberOfItems = 5;const itemPrice = 10;const totalCost = numberOfItems * itemPrice;在Good示例中，變量名稱numberOfItems、itemPrice、totalCost清楚地傳達了用途，理解起來非常方便。
編寫小而精的函數(shù)是自文檔化代碼的另一個關(guān)鍵。函數(shù)應(yīng)當功能單一，并準確命名以反映其目的。
例如：
// Badfunction processData(data: any): any { // ... // Lots of complex logic // ... return result;}// Goodfunction 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;}通過將大函數(shù)分解為名稱更具描述性的小而精函數(shù)，代碼明顯更可讀了。
在命名函數(shù)和方法時，使用描述性的名稱可以更加清楚地傳達其目的和操作。注意：應(yīng)盡量避免使用通用名稱，如handle()或process()這樣的寫法。
請看示例：
// Badfunction handleInput(input: string): void { // ...}// Goodfunction validateUserCredentials(username: string, password: string): boolean { // ...}看到了嗎？描述性名稱validateUserCredentials清楚地表明了函數(shù)的作用。現(xiàn)在，我們哪還需要額外的注釋？
TypeScript 強大的類型系統(tǒng)可以大大增強代碼的自文檔化。所以要懂得利用工具，借助 TypeScript 的功能，使代碼更具表現(xiàn)力，及早發(fā)現(xiàn)潛在的錯誤。
例如：
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 { // ...}// Badconst count: number = 10;const message: string = 'Hello, world!';// Goodconst count = 10;const message = 'Hello, world!';在 TypeScript 中處理 ID 時，建議使用強類型 ID，不要直接上字符串和數(shù)字。強類型 ID 提供了額外的類型安全性。
實現(xiàn)強類型 ID 的一種方法是使用不透明的類型：
// user.tsexport type UserId = string & { readonly __brand: unique symbol };export function createUserId(id: string): UserId { return id as UserId;}// post.tsexport type PostId = string & { readonly __brand: unique symbol };export function createPostId(id: string): PostId { return id as PostId;}這里我們使用強類型 ID，確保了UserId只分配給需要UserId的屬性和函數(shù)，PostId只分配給需要PostId的屬性和函數(shù)。
function getUserById(userId: UserId): User | undefined { // ...}const userId = createUserId('user-123');const postId = createPostId('post-456');getUserById(userId); // No errorgetUserById(postId); // Error: Argument of type 'PostId' is not assignable to parameter of type 'UserId'.強類型的 ID 有助于在編譯時捕獲潛在錯誤，使代碼更具表現(xiàn)力和自文檔化。
但是，與使用簡單的字符串類型相比，強類型 ID確實會引入一些開銷。所以我們需要根據(jù)項目的需求和規(guī)模權(quán)衡利弊。
團隊工作的時候，建立一致性至關(guān)重要，不然你有你的標準，我有我的約定，程序還怎么跑得起來？
關(guān)于一致性，有一個非常重要的方面是命名約定。最好的做法是建立一個風格指南，定義變量、函數(shù)、類和其他實體的命名方式。
例如，可以使用類似這樣的術(shù)語：
統(tǒng)一執(zhí)行術(shù)語可以確保整個代碼庫的一致性。
例如：
function getUser(userId: UserId): Promise<User> { // ...}function listUsers(): Promise<User[]> { // ...}function patchUser(userId: UserId, updatedData: Partial<User>): Promise<User> { // ...}怎么樣，是不是明顯更易于大家理解了呢。
除了命名約定之外，還可以為代碼庫的其他方面制定準則，例如文件和文件夾結(jié)構(gòu)、注釋、錯誤處理、測試和代碼格式等。
在團隊中工作時，我們有時候可能不習慣或者不贊同正在執(zhí)行的某個約定。但是，重要的是要記住，一致性和協(xié)作對于項目的成功至關(guān)重要。
即使你有不同的偏好或編碼風格，也應(yīng)該遵守約定。從而保持一個有凝聚力的代碼庫，減少混淆。
雖然自文檔化的代碼非常優(yōu)秀，但是不可否認的是，在某些情況下該上文檔就得上文檔，例如如果遇到復(fù)雜的算法和復(fù)雜的業(yè)務(wù)邏輯，你不寫注釋，簡直就不給后來人活路。
在這種情況下，可以考慮使用 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，我們可以為復(fù)雜的代碼提供額外的上下文和說明，而不會使代碼庫變得亂糟糟。
編寫自文檔化的代碼是每個開發(fā)人員都應(yīng)該努力掌握的一門藝術(shù)。
通過有意義的名稱、小而精的函數(shù)、 TypeScript 的類型系統(tǒng)以及明智地使用文檔，我們可以創(chuàng)建可讀的、富有表現(xiàn)力的和可維護的代碼。
自文檔化的代碼，可以減少對外部文檔的依賴，使我們的開發(fā)工作更輕松。
所以，下次寫代碼的時候，花點時間考慮如何使其更具自文檔性。相信我，未來的你自己和隊友都會感謝你！聽我說，謝謝你，因為有你，溫暖了四季。
本文鏈接：http://www.tebozhan.com/showinfo-26-92117-0.html快看，我的代碼能“自己說話”！
聲明：本網(wǎng)頁內(nèi)容旨在傳播知識，若有侵權(quán)等問題請及時與本網(wǎng)聯(lián)系，我們將在第一時間刪除處理。郵件：2376512515@qq.com
Copyright ? 2016-2023 天津谷騏科技有限公司 版權(quán)所有 sitemap.xml
違法及侵權(quán)請聯(lián)系：2376512515@qq.com 津ICP備18001702號
津公網(wǎng)安備 12010102000574號