-- 背景 --

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

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

-- 原理 --

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

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

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

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

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

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

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

3.追求編碼簡潔性

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

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

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

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

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

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

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

5.了解你正在做的事情

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

當(dāng)你編寫工單時，請?zhí)峁┖啙嵜髁说募?xì)節(jié)。我經(jīng)常看到這樣的糟糕工單：

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

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

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

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

對于更新和障礙，請使用工單的評論。如果需要，每天都可以這樣做。

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

9.共享工程和溝通原則

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

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

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

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

-- 總結(jié) --

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

-- 補(bǔ)充 --

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

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

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

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

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

13.提倡開放式溝通和反饋文化

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

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

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

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

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