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

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

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/process/coding-style.rst
Extension
.rst
Size
40649 bytes
Lines
1073
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.
	 */

注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行
应只声明一个数据 (不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据
写一段小注释来解释它们的用途了。


9) 你已经把事情弄糟了

Annotation

Implementation Notes