# 代碼風格遷移指南 ## Kotlin 編碼規范與 IntelliJ IDEA 格式化程序 [Kotlin 編碼規范](https://www.kotlincn.net/docs/reference/coding-conventions.html)影響了編寫地道 Kotlin 代碼的幾個方面，其中包括一組旨在提高 Kotlin 代碼可讀性的格式建議。 遺憾的是，IntelliJ IDEA 中內置的代碼格式化工具在這篇文檔發布很久之前就已經在使用了，并且現在具有默認設置，該默認設置產生的格式不同于現在建議格式。 接下來，通過改變 IntelliJ IDEA 中的默認設置并使格式與 Kotlin 編碼規范一致來消除這種隔閡似乎是符合邏輯的。但這意味著所有現有 Kotlin 項目將在安裝 Kotlin 插件后啟用新的代碼格式。這并不是插件更新的預期結果，對不對？ 這就是為什么我們有以下遷移計劃的原因： * 從 Kotlin 1.3 開始，默認情況下啟用官方代碼格式，并且僅對新項目啟用（舊風格可以手動啟用） * 現有項目的作者可以選擇遷移到現有的 Kotlin 編碼規范 * 現有項目的作者可以選擇進行顯式聲明在項目中使用舊代碼風格（這樣，將來不會因改變默認值而影響項目） * 切換到默認格式，使其與 Kotlin 1.4 中的 Kotlin 編碼規范一致 ## “Kotlin 編碼規范” 與 “IntelliJ IDEA 默認代碼風格” 之間的差異 最顯著的變化是延續縮進策略。使用雙縮進來顯示多行表達式尚未在前一行結束是一個好主意。這是一個非常簡單且通用的規則，但是以這種方式格式化時，一些 Kotlin 構造看起來有些尷尬。在 Kotlin 編碼規范中，建議在之前強制使用長延續縮進的場景中使用單個縮進  實際上，很多代碼都會受到影響，因此可以將其視為重大的代碼風格更新。 ## 遷移到新的代碼風格討論 如果沒有使用舊風格的代碼，那么從新項目開始就采用新的代碼風格應該是很自然的過程。因此，從 1.3 版開始，Kotlin IntelliJ 插件使用默認情況下啟用的編碼規范文檔中的格式創建新項目。 在現有項目中更改格式是一項更加艱巨的任務，應該與團隊討論所有注意事項然后一起開始。 更改現有項目中的代碼風格的主要缺點是，blame/annotate 版本控制系統特性將更頻繁地指向無關的提交。盡管每種版本控制系統都有某種方式可以解決此問題（IntelliJ IDEA 中可以使用[“Annotate Previous Revision”](https://www.jetbrains.com/help/idea/investigate-changes.html)），但重要的是確定新風格是否值得所有努力。將修改格式的提交與有意義的更改分開的做法可以為以后的調查提供很大幫助。 對于大型團隊來說，遷移也可能會比較困難，因為在多個子系統中提交大量文件可能會在個人的分支中產生合并沖突。 盡管每個沖突解決方案通常都很瑣碎，但明智的做法是知道當前是否正在使用大型功能分支。 通常，對于小型項目，建議一次轉換所有文件。 對于大中型項目，決定可能會很艱難。如果還沒有準備好立即更新許多文件，則可以決定逐模塊遷移，或者繼續只對已修改文件逐步遷移。 ## 遷移到新的代碼風格 可以在 `Settings → Editor → Code Style → Kotlin` 對話框中切換 Kotlin 代碼風格。將 Scheme 切換到 *Project* 并從下方選擇 `Set from... → Predefined Style → Kotlin Style Guide`。 為了向所有項目開發人員共享這些更改，必須將 `.idea/codeStyle` 文件夾提交給版本控制系統。 如果使用外部構建系統來配置項目，并且已決定不共享 `.idea/codeStyle` 文件夾，那么可以通過附加屬性強制使用 Kotlin 編碼規范： ### 在 Gradle 中 在項目根目錄的 **gradle.properties** 文件中添加 **kotlin.code.style**=**official** 屬性，并將其提交到版本控制系統。 ### 在 Maven 中 在項目根目錄的 **pom.xml** 文件中添加 **kotlin.code.style official** 屬性。 ``` <properties> <kotlin.code.style>official</kotlin.code.style> </properties> ``` _警告：_ 設置 **kotlin.code.style** 選項可能會在項目導入期間修改代碼風格方案，并且可能會更改代碼風格設置。 更新代碼風格設置后，在所需范圍的項目視圖中選擇“Reformat Code”。  對于逐步遷移，可以啟用*“File is not formatted according to project settings”（文件未根據項目設置格式化）*探查項。這將突出顯示應修改格式的地方。啟用*“Apply only to modified files”（僅應用于修改后的文件）*選項后，檢查將僅在修改后的文件中顯示格式問題。無論如何，此類文件應該盡快修改并提交。 ## 在項目中存儲舊的代碼風格 隨時可以將 IntelliJ IDEA 代碼風格明確設置為項目的正確代碼風格。為此，請在 `Settings → Editor → Code Style → Kotlin` 中將 Scheme 切換到 *Project*，然后在 *Load/Save* 選項卡中的 *"Use defaults from:"* 中選擇 *"Kotlin obsolete IntelliJ IDEA codestyle"* 。 為了在項目開發人員的 `.idea/codeStyle` 文件夾中共享更改，必須將其提交給版本控制系統。另外，**kotlin.code.style**=**obsolete** 可以用于配置了 Gradle 或 Maven 的項目。