喝咖啡休息#79。Java 開發人員犯下的 10 個阻礙他們成功的錯誤。編寫有意義的程式碼註解的開發人員指南

Java 開發人員犯下的 10 個阻礙其成功的錯誤

資料來源：Dev.to 根據我的經驗，我列出了開發人員所犯的 10 個阻礙他們成功的錯誤：

1. 不要寫單元測試

不編寫單元測試的開發人員會在程式碼中犯更多錯誤。這導致產品不穩定和客戶不滿意。

2.他們不會手動檢查代碼

即使你用單元測試完全覆蓋了你的程式碼，你仍然有可能錯過一些東西。始終建議在提交程式碼供審核之前手動測試您的程式碼。這樣您就可以在開發階段偵測到錯誤。

3.他們認為：“這永遠不會發生。”

開發人員在編寫新程式碼時經常會犯錯，認為某些場景永遠不會發生。最終事實證明他們錯了。處理所有可能執行程式碼的場景。防禦性程式設計方法將幫助您解決這個問題。

4. 得不到回饋

定期徵求其他開發人員和使用者的回饋。與您的同事分享您的意見。

5. 他們不檢查程式碼的功能。

開發人員經常編寫程式碼，但不檢查其功能。因此，當程式碼投入生產時，會產生各種問題。

6.編寫長的程式碼

編寫具有大量邏輯的長方法非常容易。透過這樣做，程式設計師可以在許多地方實現相同的邏輯。具有大量小方法的專案具有更好的程式碼重用性並且更容易維護。

7.他們不了解工具

工具是你雙手的延伸。您對它們了解得越多，您的工作效率就越高。您應該非常熟悉您正在使用的 IDE。學習快速指令，總是有一些指令可以幫助您提高工作效率。在 IntelliJ IDEA 中，這些是 Sonar Lint、Spot bugs 和 Code Metrics。

8.忽略程式碼中的問題

開發最成功產品的開發人員不斷地更改程式碼。不要害怕重構你的程式碼。如果您的程式碼經過單元測試，則回歸的可能性很小。開發人員經常忽略有問題的程式碼。作為開發人員，您有責任維護應用程式的良好狀態。因此，請解決您發現的任何問題。

9. 他們編碼時沒有意識到後果。

開發人員切勿在不了解後果的情況下更改程式碼並將其發佈到生產環境中。該程式碼可以為給定的測試值產生正確的結果。然而，在某些情況下，這可能會導致不可預測的結果並產生嚴重的問題。當開發人員使用他們不完全理解的庫中的函數時，經常會發生「不可預測」的編碼。當開發人員在不了解解決方案的情況下解決問題時，也會發生這種情況。

10.不要尋求協助

開發人員不是很善於交際的人。他們喜歡自己解決問題。但是，一個開發人員自己從頭到尾創建一個產品的時代已經結束了。軟體開發是一項團隊活動。當你在程式設計時遇到問題時，試著自己解決。但如果找不到解決方案，請不要浪費太多時間。您的一些同事很可能已經遇到了同樣的問題並且知道解決方案。這將節省時間並提高生產力。

編寫有意義的程式碼註解的開發人員指南

來源：Stepsize 在大多數情況下，您並不是唯一從事相同專案或程式碼庫的人。這意味著其他人必須理解您的程式碼。程式碼註解也是如此。開發人員經常在沒有太多背景的情況下寫出「快速而骯髒」的評論，讓他們的同事對作者想說什麼感到困惑。這是不好的做法，會造成更多的混亂而不是清晰。 擁有清晰的程式碼註解可以幫助其他開發人員。描述函數、其基本原理、輸入和輸出的程式碼註解可以加快其他開發人員的學習過程。另一方面，程式碼註解讓我們想到一個問題：值得寫它們嗎？有相當一部分開發人員反對編寫程式碼註解。原因是他們認為程式碼是不言自明的。如果其他開發人員無法透過查看程式碼來理解程式碼的用途，那麼它就是糟糕的程式碼。也許這是真的。但想想註解掉程式碼所需的小努力以及它帶來的潛在好處。程式碼註釋對於加快任何開發人員（尤其是初級開發人員）的入門過程非常重要。讓我們看看不同類型的程式碼註解。

1. 對文檔的評論。

此類註釋的主要目的是快速闡明文件或組件的用途。您可以在“index”文件的頂部添加程式碼註釋，而不是閱讀組件的整個程式碼來了解它的功能。這將有助於解釋該組件的作用。我不太喜歡這種類型的註釋，因為它使程式碼有點混亂。我認為這些類型的架構註解應該位於您的內部文件中，您可以在其中集中維護和討論專案的架構。然而，開源專案確實需要它們。

2、功能註釋。

這是最有用的評論類型。它們描述了函數的目的、參數和輸出。

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3.邏輯性的評論。

這些是函數內的註釋，用於闡明複雜的程式碼路徑。正如您可能已經猜到的，此類註釋的存在表明您的程式碼過於複雜。此外，邏輯註釋往往包含過多的詳細資訊。詳細程度會造成更多混亂並降低程式碼的可讀性。這是一個過於詳細的程式碼註解的範例。

let date = new Date(); // store today's date to calculate the elapsed time

程式碼註解：4 種註解最佳實踐

1.使用程式碼註解或標籤

許多程式語言都定義了註解程式碼的標準。Java 使用Javadoc，而 JavaScript 使用JSDoc程式碼註解系統，許多文件工具都支援該系統。對於函數，您必須包含以下程式碼標籤：

• @desc - 你的函數的描述
• @param - 函數接受的所有輸入參數。請務必指定輸入類型。
• @returns - 傳回的輸出。請務必指定輸出類型。
• @throws 是函數可以拋出的錯誤類型。
• @example - 顯示輸入和預期輸出的一個或多個範例。

下面是chunk函數的Lodash 程式碼範例。

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. 解釋你的行為的原因

許多開發人員使用註釋來描述他們的程式碼的作用。執行此操作時，請務必說明建立特定功能或元件的原因。該資訊稱為上下文。上下文對於為開發人員提供有關功能或組件背後的設計決策的更多資訊非常重要。當其他開發人員想要更改您的功能或元件時，上下文至關重要。下面您可以看到一個在沒有上下文的情況下註解程式碼的糟糕範例。

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3.不要連結到其他文件或評論

不建議連結到其他程式碼註解或解釋功能或組件的內部文件。

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. 編碼時寫註釋

這似乎是顯而易見的，但許多開發人員（包括我自己）忽略了這條規則。留下註釋以供以後使用是不好的，因為您可能會忘記您編寫的一些邏輯，這將導致程式碼註解品質較低。如果您連續幾天處理同一個拉取請求，則尤其如此。最好在剛完成一個功能或模組時寫評論。請記住使程式碼註釋盡可能簡短。您不需要花費比編寫程式碼本身更多的時間來編寫註解。