-- 背景 --

當(dāng)你開(kāi)始一家新公司并且必須非常快速地交付一個(gè)MVP以評(píng)估市場(chǎng)適應(yīng)性時(shí)，你可以原諒自己的粗心。在那個(gè)階段，目標(biāo)是進(jìn)行原始實(shí)驗(yàn)，以便迅速評(píng)估你正在創(chuàng)建的產(chǎn)品的可行性，并快速進(jìn)行變更。在這個(gè)階段，你通常是一個(gè)小團(tuán)隊(duì)，每個(gè)人都彼此了解并始終保持溝通。

但隨著公司的發(fā)展，這種操作方式無(wú)法擴(kuò)展，溝通變得越來(lái)越大的問(wèn)題。以下是你可以使用的十個(gè)實(shí)踐，以顯著改善公司（或團(tuán)隊(duì)）的溝通。

-- 原理 --

這些戒律的總體目標(biāo)是最小化上下文切換的成本，以便你的工程師可以更快地進(jìn)入流程。這也意味著更快地提供更好的軟件。

這些做法不僅有利于你的同事，而且在你回顧自己的舊工作時(shí)也有利于未來(lái)的你。

1.把同事當(dāng)作客戶對(duì)待

你最重要的客戶是價(jià)值流中的下一步。如果你是一個(gè)與基礎(chǔ)設(shè)施工程師緊密合作的開(kāi)發(fā)人員，請(qǐng)確保你的工作與基礎(chǔ)設(shè)施兼容（考慮12因素應(yīng)用程序）。如果你是一名運(yùn)維工程師，請(qǐng)確保開(kāi)發(fā)人員可以自助獲取資源并部署應(yīng)用程序。

確保你持續(xù)獲得同事的反饋，并根據(jù)需要調(diào)整以滿足他們的需求并減輕他們的工作負(fù)擔(dān)。

2.像準(zhǔn)備要開(kāi)源一樣創(chuàng)建代碼倉(cāng)庫(kù)

我曾在許多地方工作過(guò)，那里的代碼倉(cāng)庫(kù)非常混亂，有多余的文件和代碼，沒(méi)有README文件，文件結(jié)構(gòu)混亂，甚至還有密鑰。每當(dāng)你創(chuàng)建一個(gè)倉(cāng)庫(kù)時(shí)，請(qǐng)將其視為要開(kāi)源，并考慮到那些不認(rèn)識(shí)你或你的工作的人；他們?nèi)绾沃肋@個(gè)倉(cāng)庫(kù)是關(guān)于什么的？

3.追求編碼簡(jiǎn)潔性

有些工程師編寫復(fù)雜的代碼，因?yàn)樗麄冇X(jué)得自己顯得更聰明。我甚至遇到過(guò)一些認(rèn)為代碼行數(shù)越多意味著工作產(chǎn)出越多的人。

絕對(duì)不，絕對(duì)不是這樣。編碼就像寫作一樣，當(dāng)寫得清晰簡(jiǎn)潔時(shí)，會(huì)更優(yōu)雅、更簡(jiǎn)單、更容易理解。我理解想要寫更多代碼行的想法；如果經(jīng)理只看到五行代碼，他們可能會(huì)覺(jué)得你懶惰。如果你在這樣的公司工作，我建議收拾行李換工作。你需要在一個(gè)鼓勵(lì)工程技藝的組織中工作；這對(duì)你的技能和心理健康最好。

編寫簡(jiǎn)潔的代碼需要更多的時(shí)間和精力。它還與設(shè)計(jì)緊密相連；如果你在鍵盤上猛擊一堆代碼，你很可能對(duì)整個(gè)過(guò)程并不十分了解，并最終交付一份令人困惑的雜亂無(wú)章的文檔和自動(dòng)化過(guò)程。

4.將Kondo原則應(yīng)用于你的文件結(jié)構(gòu)

Marie Kondo關(guān)于房屋整理的哲學(xué)很簡(jiǎn)單：只保留那些“激發(fā)喜悅”的東西，讓一切整潔有序。

文件可能沒(méi)有物品那么令人愉悅，但是你不應(yīng)該保留任何不起作用的東西。工程師在代碼倉(cāng)庫(kù)里摸索、嘗試解決問(wèn)題的各種不同方法，然后在成功后留下所有東西，這種情況太常見(jiàn)了。這種混亂使得后來(lái)找到該倉(cāng)庫(kù)并嘗試?yán)斫馄淠康牡娜朔浅＠Щ蟆?duì)于下一個(gè)需要清理你的混亂的人來(lái)說(shuō)，這也更具挑戰(zhàn)性，因?yàn)樗麄冃枰廊绾蝿h除而不改變你的代碼的功能。請(qǐng)記住，你可以在git中恢復(fù)刪除的所有內(nèi)容，所以在清理時(shí)要毫不留情！

文件結(jié)構(gòu)同樣至關(guān)重要。我曾與許多人合作，他們創(chuàng)建代碼倉(cāng)庫(kù)的文件結(jié)構(gòu)就像我母親整理她的廚房一樣——她知道每樣?xùn)|西都放在哪里，但其他人卻不知道！一個(gè)有組織的文件結(jié)構(gòu)和合適的目錄名稱使理解變得更容易。為需要解釋的任何目錄添加README.md文件。

5.了解你正在做的事情

這一點(diǎn)似乎很明顯，但你不知道我遇到了多少次顯而易見(jiàn)的是工程師不知道自己在做什么的代碼。

我遇到的最惡劣的例子是開(kāi)發(fā)人員編輯NGINX和Apache配置文件，試圖解決他們的Java代碼中的問(wèn)題，而這些問(wèn)題本應(yīng)該在代碼中解決。他們從StackOverflow粘貼配置行，看看是否有效；有時(shí)有效，有時(shí)沒(méi)有任何作用，但他們總是把所有內(nèi)容留在文件中。結(jié)果是，我繼承了龐大的配置文件，沒(méi)有人能理解，也沒(méi)有人敢編輯，擔(dān)心會(huì)破壞某些功能。

不要盲目地復(fù)制粘貼StackOverflow上的代碼。嘗試?yán)斫饽阏迟N的代碼，并附上來(lái)源和解釋的評(píng)論。ChatGPT和其他AI工具會(huì)使這個(gè)問(wèn)題變得更糟；如果你使用這樣的工具，試著讓AI先解釋一下，并添加相關(guān)的注釋！

6.根據(jù)上下文進(jìn)行文檔記錄，而不是全面記錄

當(dāng)敏捷宣言說(shuō)“優(yōu)先考慮有用的軟件，而非詳盡的文檔”時(shí)，他們并不是說(shuō)完全不需要文檔。但這并不意味著你需要過(guò)度記錄所有東西。

上下文文檔旨在為了解、操作和診斷應(yīng)用程序的人提供所需的所有信息。為什么、什么時(shí)候、誰(shuí)、什么和怎么做；先決條件、示例、如何測(cè)試應(yīng)用程序——任何你需要開(kāi)始的東西。

想象一下，我給你一個(gè)包含50種不同類型的草藥和廚房食材描述的清單——這就是詳盡的文檔。現(xiàn)在想象一下，我讓你用這些東西做飯。如果沒(méi)有任何先前的知識(shí)，你能做到嗎？可能不能，但這就是大部分軟件文檔的現(xiàn)狀（想想man頁(yè)）。

相反，如果我給你一些解釋如何使用這些草藥的食譜會(huì)更有幫助——這就是上下文文檔。提供上下文文檔對(duì)用戶更有價(jià)值，而且可能花費(fèi)更少的時(shí)間。

如果你的上下文文檔臃腫且難以理解，問(wèn)問(wèn)自己以下問(wèn)題，我是否可以通過(guò)設(shè)計(jì)我的工作來(lái)減輕這種情況？答案通常是肯定的，因?yàn)榱钊死Щ蠛瓦^(guò)多的文檔通常掩蓋了糟糕的設(shè)計(jì)。

始終詢問(wèn)同事和其他團(tuán)隊(duì)你的文檔是否合理，并在需要時(shí)改進(jìn)。目標(biāo)是他們不需要向你提問(wèn)，他們可以自己有效地解決問(wèn)題。

7.將文檔與源代碼保持緊密聯(lián)系

如果索倫在指環(huán)上附上了一個(gè)很好的README.md文件，甘道夫可能會(huì)更早地了解到指環(huán)。

許多公司有一個(gè)趨勢(shì)，所有文檔都放在Confluence中；這是一個(gè)好做法。然而，這通常意味著將文檔與代碼庫(kù)分開(kāi)。我認(rèn)為這種做法存在兩個(gè)問(wèn)題：

1. 你需要維護(hù)兩個(gè)真實(shí)來(lái)源。
2. 你必須相信你的客戶知道這個(gè)Confluence頁(yè)面在哪里，以及她是否有權(quán)限訪問(wèn)。

讓所有內(nèi)容都集中在一個(gè)地方，可以讓你和你的客戶更簡(jiǎn)單。我建議在Confluence中引用代碼庫(kù)，添加對(duì)其功能的描述，并提供指向README.md的鏈接以獲取更多文檔。

在wiki中維護(hù)適用于多個(gè)代碼庫(kù)的通用文檔或具有復(fù)雜格式的教程，同時(shí)在需要時(shí)提供指向代碼庫(kù)中README.md文件的鏈接。這樣，更新README.md文件的詳細(xì)信息會(huì)更容易。

或者，你可以使用任何簡(jiǎn)化此過(guò)程的工具，讓文檔方便使用且集中存放，同時(shí)只需編輯一次。最重要的是，查看你的代碼的人應(yīng)該知道文檔在哪里并能夠訪問(wèn)它。

8.為同事編寫有意義的工單

當(dāng)你編寫工單時(shí)，請(qǐng)?zhí)峁┖?jiǎn)潔明了的細(xì)節(jié)。我經(jīng)常看到這樣的糟糕工單：

一句話、含糊不清的工單：比如“為x創(chuàng)建角色”或“為y提供根權(quán)限”并不是好的工單。

雜亂無(wú)章、冗余信息過(guò)多的工單：一個(gè)常見(jiàn)的例子是粘貼一系列電子郵件，這樣需要完成工作的人必須閱讀整個(gè)交流過(guò)程并試圖理解其中的意義。這樣做浪費(fèi)了需要完成工作的人大量時(shí)間去建立上下文。

相反，你可以使用這樣的結(jié)構(gòu)：

• 描述：包括上下文和原因。
• 驗(yàn)收標(biāo)準(zhǔn)：包括驗(yàn)收人。
• 有用的來(lái)源：指向可能有助于完成任務(wù)的資源的鏈接。
• 工作位置：指派人在需要時(shí)可以填寫。

對(duì)于更新和障礙，請(qǐng)使用工單的評(píng)論。如果需要，每天都可以這樣做。

這樣編寫工單非常有助于了解你的看板以及每個(gè)人正在從事的工作。這也使得查看工作流程和常見(jiàn)障礙更容易，避免了每天站立會(huì)議上信息未被記錄且流程被中斷的情況。

9.共享工程和溝通原則

僅憑你自己產(chǎn)出優(yōu)秀的工作是不夠的，如果你必須不斷地修復(fù)他人的工作或試圖理解他們的混亂，有時(shí)候最好退一步，與團(tuán)隊(duì)成員或其他與代碼有關(guān)的團(tuán)隊(duì)進(jìn)行討論，并盡早解決這些問(wèn)題。

明確并有效地定義什么是優(yōu)秀的工作以及如何實(shí)現(xiàn)它，制定一些指導(dǎo)方針并與你的團(tuán)隊(duì)和整個(gè)公司分享——最重要的是，承諾遵循這些指導(dǎo)方針！

10.將大部分努力用于創(chuàng)新和優(yōu)雅的設(shè)計(jì)

確保花時(shí)間做好工作；如果產(chǎn)品負(fù)責(zé)人或其他人試圖推動(dòng)你更快地交付，請(qǐng)尋求折衷，并解釋現(xiàn)在節(jié)省時(shí)間，將來(lái)會(huì)花費(fèi)更多時(shí)間和金錢。敏捷并不意味著高速開(kāi)發(fā)；它意味著快速、短小的高質(zhì)量軟件迭代，遵循節(jié)省時(shí)間的設(shè)計(jì)原則。

-- 總結(jié) --

最近，我對(duì)平臺(tái)工程和內(nèi)部開(kāi)發(fā)者平臺(tái)的實(shí)施變得非常熱衷，因?yàn)橥ㄟ^(guò)將工作哲學(xué)轉(zhuǎn)向自助服務(wù)和開(kāi)發(fā)者體驗(yàn)（DX），上述所有原則都成為開(kāi)發(fā)的基本目標(biāo)。然而，了解良好溝通的原則以及如何實(shí)施它們是了解為什么它們可以長(zhǎng)期節(jié)省時(shí)間和精力的基本要求。

-- 補(bǔ)充 --

以下五點(diǎn)補(bǔ)充建議將有助于提高團(tuán)隊(duì)在工程交流方面的效率和協(xié)作，從而提高項(xiàng)目的成功率。

11.定期進(jìn)行代碼審查和團(tuán)隊(duì)討論

通過(guò)定期進(jìn)行代碼審查和團(tuán)隊(duì)討論，可以確保團(tuán)隊(duì)成員共享知識(shí)、了解彼此的工作以及相互學(xué)習(xí)。這有助于減少誤解，并在項(xiàng)目中建立統(tǒng)一的編碼和文檔風(fēng)格。

12.使用可視化工具來(lái)解釋復(fù)雜概念

利用流程圖、架構(gòu)圖和其他可視化工具來(lái)解釋復(fù)雜的系統(tǒng)和概念。這將有助于提高團(tuán)隊(duì)對(duì)項(xiàng)目的理解，并使概念更容易傳達(dá)給新成員或其他團(tuán)隊(duì)。

13.提倡開(kāi)放式溝通和反饋文化

鼓勵(lì)團(tuán)隊(duì)成員在遇到問(wèn)題或不清楚某些事物時(shí)，主動(dòng)尋求幫助和建議。通過(guò)建立一種積極的反饋文化，可以確保問(wèn)題得到解決，并鼓勵(lì)團(tuán)隊(duì)成員互相學(xué)習(xí)。

14.定期進(jìn)行知識(shí)分享會(huì)

組織定期的知識(shí)分享會(huì)，讓團(tuán)隊(duì)成員分享他們?cè)陧?xiàng)目中學(xué)到的新知識(shí)、技術(shù)和最佳實(shí)踐。這不僅可以提高團(tuán)隊(duì)的技能水平，還有助于建立團(tuán)隊(duì)凝聚力。

15.利用協(xié)作工具進(jìn)行有效溝通

使用協(xié)作工具，如Slack、Microsoft Teams或其他即時(shí)通訊工具，以便團(tuán)隊(duì)成員可以輕松地共享信息、討論問(wèn)題并協(xié)作解決問(wèn)題。同時(shí)，利用項(xiàng)目管理工具（如Jira或Trello）跟蹤任務(wù)和進(jìn)度，確保團(tuán)隊(duì)工作得當(dāng)且透明。