コードスタイル-コメント
15379 ワード
単行注釈は
もっと派手な形もあります.
注釈を使う場合は主に以下のようなものがあります.
1.ソースファイル全体の上部コメント.このモジュールに関する情報(ファイル名、作成者、バージョン履歴など)を説明し、先頭にインデントしません.たとえば、カーネルソースディレクトリの
2、関数コメント.この関数の機能、パラメータ、戻り値、エラーコードなどを説明し、関数定義の上側に書き、この関数定義との間に空白行を残さず、先頭に字を書いてインデントしない.
3、相対的に独立した文グループコメント.この一連の文について特に説明します.文グループの上側に書いてあり、この文グループとの間に空白行は残さず、現在の文グループのインデントと一致します.
4、コード行の右側にある短いコメント.現在のコード行について特に説明します.一般的には、1行のコメントとコードの間に少なくとも1つのスペースで区切られており、1つのソースファイル内のすべての右側のコメントは上下に揃えられることが望ましいです.コメントは1行のコードの間に挿入できますが、このように書くことはお勧めしません.カーネルソースディレクトリの下にある
[CodingStyle]では特に,関数内の注釈はできるだけ少なく用いることが指摘されている.注釈を書くのは主にあなたのコード「何ができるか」(例えば関数インタフェース定義)を説明するためで、「どのようにするか」を説明するためではなく、コードが十分にはっきり書かれている限り、「どのようにするか」は一目瞭然で、注釈で説明しなければならない場合は、特に注意が必要な場所でない限り、関数内の注釈を使用するコードの可読性が悪いことを示します.
5、複雑な構造体定義は関数よりも注釈を必要とする.たとえば、カーネルソースディレクトリの
6、複雑なマクロ定義と変数宣言にも注釈が必要です.たとえば、カーネルソースディレクトリの
The ending...
/*␣comment␣*/の形式を採用し、スペースで定義子と文字を分離しなければならない.複数行コメントの最も一般的な形式は、次のとおりです./*
␣*␣Multi-line
␣*␣comment
␣*/もっと派手な形もあります.
/*************\
* Multi-line *
* comment *
\*************/注釈を使う場合は主に以下のようなものがあります.
1.ソースファイル全体の上部コメント.このモジュールに関する情報(ファイル名、作成者、バージョン履歴など)を説明し、先頭にインデントしません.たとえば、カーネルソースディレクトリの
kernel/sched.cファイルの先頭:/*
* kernel/sched.c
*
* Kernel scheduler and related syscalls
*
* Copyright (C) 1991-2002 Linus Torvalds
*
* 1996-12-23 Modified by Dave Grothe to fix bugs in semaphores and
* make semaphores SMP safe
* 1998-11-19 Implemented schedule_timeout() and related stuff
* by Andrea Arcangeli
* 2002-01-04 New ultra-scalable O(1) scheduler by Ingo Molnar:
* hybrid priority-list and round-robin design with
* an array-switch method of distributing timeslices
* and per-CPU runqueues. Cleanups and useful suggestions
* by Davide Libenzi, preemptible kernel bits by Robert Love.
* 2003-09-03 Interactivity tuning by Con Kolivas.
* 2004-04-02 Scheduler domains code by Nick Piggin
*/2、関数コメント.この関数の機能、パラメータ、戻り値、エラーコードなどを説明し、関数定義の上側に書き、この関数定義との間に空白行を残さず、先頭に字を書いてインデントしない.
3、相対的に独立した文グループコメント.この一連の文について特に説明します.文グループの上側に書いてあり、この文グループとの間に空白行は残さず、現在の文グループのインデントと一致します.
4、コード行の右側にある短いコメント.現在のコード行について特に説明します.一般的には、1行のコメントとコードの間に少なくとも1つのスペースで区切られており、1つのソースファイル内のすべての右側のコメントは上下に揃えられることが望ましいです.コメントは1行のコードの間に挿入できますが、このように書くことはお勧めしません.カーネルソースディレクトリの下にある
lib/radix-tree.cファイルの1つの関数には、次の3つの注釈が含まれています./**
* radix_tree_insert - insert into a radix tree
* @root: radix tree root
* @index: index key
* @item: item to insert
*
* Insert an item into the radix tree at position @index.
*/
int radix_tree_insert(struct radix_tree_root *root,
unsigned long index, void *item)
{
struct radix_tree_node *node = NULL, *slot;
unsigned int height, shift;
int offset;
int error;
/* Make sure the tree is high enough. */
if ((!index && !root->rnode) ||
index > radix_tree_maxindex(root->height)) {
error = radix_tree_extend(root, index);
if (error)
return error;
}
slot = root->rnode;
height = root->height;
shift = (height-1) * RADIX_TREE_MAP_SHIFT;
offset = 0; /* uninitialised var warning */
do {
if (slot == NULL) {
/* Have to add a child node. */
if (!(slot = radix_tree_node_alloc(root)))
return -ENOMEM;
if (node) {
node->slots[offset] = slot;
node->count++;
} else
root->rnode = slot;
}
/* Go a level down */
offset = (index >> shift) & RADIX_TREE_MAP_MASK;
node = slot;
slot = node->slots[offset];
shift -= RADIX_TREE_MAP_SHIFT;
height--;
} while (height > 0);
if (slot != NULL)
return -EEXIST;
BUG_ON(!node);
node->count++;
node->slots[offset] = item;
BUG_ON(tag_get(node, 0, offset));
BUG_ON(tag_get(node, 1, offset));
return 0;
}[CodingStyle]では特に,関数内の注釈はできるだけ少なく用いることが指摘されている.注釈を書くのは主にあなたのコード「何ができるか」(例えば関数インタフェース定義)を説明するためで、「どのようにするか」を説明するためではなく、コードが十分にはっきり書かれている限り、「どのようにするか」は一目瞭然で、注釈で説明しなければならない場合は、特に注意が必要な場所でない限り、関数内の注釈を使用するコードの可読性が悪いことを示します.
5、複雑な構造体定義は関数よりも注釈を必要とする.たとえば、カーネルソースディレクトリの
kernel/sched.cファイルには、次のような構造体が定義されています./*
* This is the main, per-CPU runqueue data structure.
*
* Locking rule: those places that want to lock multiple runqueues
* (such as the load balancing or the thread migration code), lock
* acquire operations must be ordered by ascending &runqueue.
*/
struct runqueue {
spinlock_t lock;
/*
* nr_running and cpu_load should be in the same cacheline because
* remote CPUs use both these fields when doing load calculation.
*/
unsigned long nr_running;
#ifdef CONFIG_SMP
unsigned long cpu_load[3];
#endif
unsigned long long nr_switches;
/*
* This is part of a global counter where only the total sum
* over all CPUs matters. A task can increase this counter on
* one CPU and if it got migrated afterwards it may decrease
* it on another CPU. Always updated under the runqueue lock:
*/
unsigned long nr_uninterruptible;
unsigned long expired_timestamp;
unsigned long long timestamp_last_tick;
task_t *curr, *idle;
struct mm_struct *prev_mm;
prio_array_t *active, *expired, arrays[2];
int best_expired_prio;
atomic_t nr_iowait;
#ifdef CONFIG_SMP
struct sched_domain *sd;
/* For active balancing */
int active_balance;
int push_cpu;
task_t *migration_thread;
struct list_head migration_queue;
int cpu;
#endif
#ifdef CONFIG_SCHEDSTATS
/* latency stats */
struct sched_info rq_sched_info;
/* sys_sched_yield() stats */
unsigned long yld_exp_empty;
unsigned long yld_act_empty;
unsigned long yld_both_empty;
unsigned long yld_cnt;
/* schedule() stats */
unsigned long sched_switch;
unsigned long sched_cnt;
unsigned long sched_goidle;
/* try_to_wake_up() stats */
unsigned long ttwu_cnt;
unsigned long ttwu_local;
#endif
};6、複雑なマクロ定義と変数宣言にも注釈が必要です.たとえば、カーネルソースディレクトリの
include/linux/jiffies.hファイルの定義:/* TICK_USEC_TO_NSEC is the time between ticks in nsec assuming real ACTHZ and */
/* a value TUSEC for TICK_USEC (can be set bij adjtimex) */
#define TICK_USEC_TO_NSEC(TUSEC) (SH_DIV (TUSEC * USER_HZ * 1000, ACTHZ, 8))
/* some arch's have a small-data section that can be accessed register-relative
* but that can only take up to, say, 4-byte variables. jiffies being part of
* an 8-byte variable may not be correctly accessed unless we force the issue
*/
#define __jiffy_data __attribute__((section(".data")))
/*
* The 64-bit value is not volatile - you MUST NOT read it
* without sampling the sequence number in xtime_lock.
* get_jiffies_64() will do this for you as appropriate.
*/
extern u64 __jiffy_data jiffies_64;
extern unsigned long volatile __jiffy_data jiffies;The ending...