Categories
程式開發

再無下文:Kubernetes上眾多TODO註釋遭到遺忘


Kubernetes是個體量可觀的大項目。這裡說的“大”,指的不單單是願景野心,同時也體現在源代碼量層面。截至本文撰寫之時,該項目擁有超過86000條提交、2000多位貢獻者、2000多個開放問題、1000多個公開PR以及超過61000星。絕非虛言,大家打開項目的GitHub頁面即可求證。

根據計算,目前Kubernetes項目的go源代碼量超過430萬行(總代碼量已經超過520萬行),“actual”行超過300萬,註釋行也已經達到70萬以上。項目的總文件數為16000多個,其中包括vendor/目錄。

我們的工作是通過一套代碼庫顯示項目中的TODO註釋量,希望幫助開發人員藉此執行各類基礎性項目管理流程。

這一次,我們決定利用一款小型TODO查找器對Kubernetes源代碼進行一番篩查,看看結果究竟如何。下面來看我們的發現。

我們針對commit 9bf52c2的源代碼運行了tickgit。該CSV輸出結果隨後會被導入至SQLite以運行其他後續查詢。請注意,該工具僅從已檢出的提交當中查找TODO註釋;曾經添加,但隨後被刪除的TODO部分不會被計入在內。因此,我們得出的數字將僅反映查詢時仍“活動”於代碼庫之內的TODO註釋。

  • 總體情況(9bf52c2)共存在來自363位不同作者、1230個文件的2380條TODO
  • 其中460條TODO註釋指向明確待辦人,例如 // TODO (patrickdevivo) Fix the …
  • 截至目前,2019年年內新增TODO數量為489條
  • 單一TODO的平均存在周期為860天(折合2.3年)
  • 最早的現存TODO創建於2014年6月6日 來自首次提交
  • 最新的TODO來自2019年12月9日
  • 單一文件中的最高TODO數量為33條
  • deads2k提交的現存TODO(git blame)量最高,為147條
  • 此次提交一次性添加了最多TODO(仍在源中),為64條
結果匯總計數 文件路徑
33 cluster/gce/util.sh
25 pkg/apis/core/types.go
23 staging/src/k8s.io/api/core/v1/types.go
21 staging/src/k8s.io/legacy-cloud-providers/aws/aws.go
20 staging/src/k8s.io/code-generator/cmd/conversion-gen/generators/conversion.go
20 pkg/apis/core/validation/validation.go
16 test/e2e/network/service.go
16 pkg/kubelet/kubelet.go
14 test/e2e/framework/util.go
14 pkg/kubelet/kubelet_pods.go

包含TODO最多的文件

作者 計數
deads2k 147
Clayton Coleman 105
Chao Xu 99
Dr. Stefan Schimanski 93
Jordan Liggitt 81
David Eads 60
Random-Liu 54
Wojciech Tyczynski 50
Yu-Ju Hong 43
Prashanth Balasubramanian 38

提交TODO最多的作者

計數 sha
64 6a4d5cd7cc58e28c20ca133dab7b0e9e56192fe3
19 e01ff1641c7321ac81fe5775f6ccb21aa6775c04
19 4fb28dafad121e163fa86dc90067ce3d14415811
18 adb75e1fd17b11e6a0256a4984ef9b18957d94ce
14 963c85e1c807efcdbb82dd44439dc3c55f6a0bfd
14 8b17db7e0c4431cd5fd9a5d9a3ab11b04e2f0a7e
13 f0f78299348afcf770d4e8d89dcea82f80811b28
11 d0b94538b9744d0c06df6ddec2604be168568f9d
10 f1248b9c829e225138ab6d6234221c63092f7592
10 cd663d7ad00937cffa8a09e4761acb95d34c89a3

添加TODO最多的提交

計數 年份
34 2014
249 2015
523 2016
650 2017
435 2018
489 2019

各年份新增TODO數量

大家可以使用tickgit todos –csv-output獲取原始TODO數據,得出與我們相似的查詢結果。以上匯總內容來自SQLite。

結論與問題這些結果未經任何處理與預設,完全是對Kubernetes源代碼當中TODO註釋的即時整理。我們對TODO的主要來源也比較明確,其中大部分由Kubernetes項目的頂尖貢獻者創建。

我們還發現,雖然Kubernetes這種大規模項目的體量可觀,但開發人員在TODO註釋方面的行為模式與小項目沒什麼區別,只是絕對數量更高。

一大重要發現是,與GitHub提問相比,TODO註釋的數量更多。這是種有趣的現象,因為TODO代表著大量潛在的“工作內容”或者待辦事項,而且除非我們親身參與源代碼開發,否則TODO對普通用戶的提示性並不強。

核心貢獻者們可能非常熟悉自己負責的代碼庫部分,也對自己的TODO與“潛在工作”了然於胸。但是,這一切在外部觀察者看來毫無透明性可言。相比之下,GitHub提問或者其他公開的交互跟踪機制顯然更為便捷易用。

很多開發者朋友應該都清楚,軟件項目本身類似於“生命體”。它會不時變化、持續改進、不斷完善,同時帶來大量討論。工作流與流程安排非常重要,因為只有不斷反思才能成就高質量的代碼。通過在Kubernetes源代碼當中的TODO註釋,我們得以一窺反思的力量。然而,由於缺少相關基準,TODO註釋的平均存在周期長達2.3年,相當誇張。不過這裡我們不敢評價太多,畢竟只有真正熟知項目內情的核心貢獻者,才能斷言2.3年算不算太長。接下來如果有機會,我們打算將Kubernetes的TODO週期與其他大型開源項目進行一番比較,相信結果會更有啟發意義。

如果要對代碼庫中的TODO註釋進行更深入的分析,我們可能需要縱觀項目發展歷程中曾經出現的所有TODO,而不僅僅是仍存在於當前源代碼中的TODO。

  • TODO的平均關閉週期是多長?
  • TODO註釋的平均生命週期是多長?
  • 不同流行代碼庫之間的TODO註釋有何區別?

這事……有意義嗎?當然有意義。 TODO註釋所涉及的工作類型往往是那種不值得單獨發一條申請,但卻又比較重要的內容,因此有必要在代碼行內做出註釋與描述(當然,很多TODO也會引用問題/申請)。由於屬於代碼的組成部分,因為TODO與待完成工作往往“更加接近”。 TODO易於添加,但也很容易被遺忘(目前,Kubernetes源代碼當中仍然包含1800多條2019年之前添加的TODO)。

我們希望能夠創建一款顯示相關代碼元數據的工具,確保軟件開發人員能夠更輕鬆地完成規模不同、類型各異的項目,而顯示TODO信息只是其中的一部分——當然,也是非常重要的一部分。

原文鏈接

https://medium.com/@augmentable/looking-at-kubernetes-2k-todo-comments-b2db42dc7fdb