代碼注釋的副作用有哪些

本篇內容介紹了“代碼注釋的副作用有哪些”的有關知識，在實際案例的操作過程中，不少人都會遇到這樣的困境，接下來就讓小編帶領大家學習一下如何處理這些情況吧！希望大家仔細閱讀，能夠學有所成！

代碼注釋 vs 代碼文檔

1. 代碼注釋包含代碼文檔（類，方法，屬性，常量描述）

2. 代碼文檔必要，非代碼文檔非必要

代碼注釋的使用場景

1. 新同學上手，快速把握脈絡。

2. 復用方法時存疑，快速查詢注釋避免方法副作用。

3. 回顧代碼實現，還原原始實現意圖。

4. 專制不服管教兒童，毀滅技術信仰。（定義模糊，可用于指鹿為馬）

代碼注釋的副作用

1. 好代碼 > 爛代碼 + 注釋（影響代碼整潔）

2. 攜帶歷史包袱（歷史TODO，歷史背景細節） => 不敢刪

3. 無標準，無法量化，無法評估（個體差異大，強行推廣，易影響開發效率，推行代碼注釋到不看代碼注釋）

4. 可能導致團隊陷入不思代碼結構設計的混沌狀態

代碼注釋示例

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

    /**
     * Tests if the specified object is a key in this table.
     *
     * @param  key possible key
     * @return {@code true} if and only if the specified object
     *         is a key in this table, as determined by the
     *         {@code equals} method; {@code false} otherwise
     * @throws NullPointerException if the specified key is null
     */
    public boolean containsKey(Object key) {
        return get(key) != null;
    }

代碼注釋的個人建議

1. 控制注釋粒度（一般到代碼文檔級別即可，當你需要細粒度注釋時，先考慮這段邏輯是否改抽出來寫）

2. 明晰注釋作用域（描述一行代碼，描述一個Loop）

3. 注釋不留包袱（歷史背景信息，未處理TODO，保持基線文檔級別的代碼注釋）

4. 作為復雜邏輯的補充解釋（中間結果格式示例，為什么捕獲異常，為什么不）

5. 理解代碼注釋的目標，可讀，提效（換位思考）

代碼注釋共識如何達成？

1. 腦暴

2. 試行

3. 階段回收意見，案例分享（去差異化）

“代碼注釋的副作用有哪些”的內容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業相關的知識可以關注億速云網站，小編將為大家輸出更多高質量的實用文章！