Documentation/translations/zh_TW/process/coding-style.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_TW/process/coding-style.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_TW/process/coding-style.rst
Extension
.rst
Size
41056 bytes
Lines
1088
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

if (condition1) {
			while (loop1) {
				...
			}
			result = 1;
			goto out_free_buffer;
		}
		...
	out_free_buffer:
		kfree(buffer);
		return result;
	}

一個需要注意的常見錯誤是 ``單 err 錯誤`` ，就像這樣：

.. code-block:: c

	err:
		kfree(foo->bar);
		kfree(foo);
		return ret;

這段代碼的錯誤是，在某些退出路徑上 ``foo`` 是 NULL。通常情況下，通過把它分離
成兩個錯誤標籤 ``err_free_bar:`` 和 ``err_free_foo:`` 來修復這個錯誤：

.. code-block:: c

	err_free_bar:
		kfree(foo->bar);
	err_free_foo:
		kfree(foo);
		return ret;

理想情況下，你應該模擬錯誤來測試所有退出路徑。


8) 註釋
-------

註釋是好的，不過有過度註釋的危險。永遠不要在註釋裏解釋你的代碼是如何運作的：
更好的做法是讓別人一看你的代碼就可以明白，解釋寫的很差的代碼是浪費時間。

一般來說你用註釋告訴別人你的代碼做了什麼，而不是怎麼做的。也請你不要把
註釋放在一個函數體內部：如果函數複雜到你需要獨立的註釋其中的一部分，你很可能
需要回到第六章看一看。你可以做一些小注釋來註明或警告某些很聰明 (或者槽糕) 的
做法，但不要加太多。你應該做的，是把註釋放在函數的頭部，告訴人們它做了什麼，
也可以加上它做這些事情的原因。

當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。

長 (多行) 註釋的首選風格是：

.. code-block:: c

	/*
	 * This is the preferred style for multi-line
	 * comments in the Linux kernel source code.
	 * Please use it consistently.
	 *
	 * Description:  A column of asterisks on the left side,
	 * with beginning and ending almost-blank lines.
	 */

對於在 net/ 和 drivers/net/ 的文件，首選的長 (多行) 註釋風格有些不同。

.. code-block:: c

	/* The preferred comment style for files in net/ and drivers/net
	 * looks like this.

Annotation

Implementation Notes