empire/empserver
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs/coding: Explain function/struct/union comment conventions

Browse source 
Signed-off-by: Markus Armbruster <armbru@pond.sub.org>
This commit is contained in:
Markus Armbruster 2015-06-14 11:39:07 +02:00
parent eba87789ab
commit 6b6708a01b
1 changed files with 30 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

36
doc/coding
View file

@ -170,7 +170,7 @@ above the definition.
Comments to the right of code should start in column 32 if possible Comments to the right of code should start in column 32 if possible
(counting from zero). (counting from zero).
Comment lines should be indented exactly like the code the belong to. Comment lines should be indented exactly like the code they belong to.
You are encouraged to format multi-line comments like this: You are encouraged to format multi-line comments like this:
@ -193,7 +193,6 @@ Do not use
because they are not portable C89. because they are not portable C89.
Conditional compilation Conditional compilation
Unless the conditional code is very short, please comment it like Unless the conditional code is very short, please comment it like
@ -247,10 +246,35 @@ Comments
Every file should have a file comment FIXME Every file should have a file comment FIXME
Every function should have a function comment that describes what it Every function should have a function comment that describes what it
does. FIXME elaborate. Writing such comments helps both future does, unless it's blatantly obvious. If the function is longer than a
maintainers and yourself: if it's too hard to write a concise function few lines, it's almost certainly not obvious.
comment, then your function is likely too complicated and could use a
redesign. The function comment should serve as a contract: state the
preconditions, side effects, return values. Make sure to cover error
conditions.
Writing such comments helps both future maintainers and yourself: when
writing a concise function comment is too hard, then your function is
likely too complicated and could use a redesign.
Use @param to refer to parameters. Use func() to refer to functions
or function-like macros. Use arr[] to refer to arrays. This is to
make the references stand out and to avoid ambiguity.
Example:
/*
* Read update schedule from file @fname.
* Put the first @n-1 updates after @t0 into @sched[] in ascending order,
* terminated with a zero.
* Use @anchor as initial anchor for anchor-relative times.
* Return 0 on success, -1 on failure.
*/
int
read_schedule(char *fname, time_t sched[], int n, time_t t0, time_t anchor)
When documenting a struct or union, use @member to refer to its
members.
The existing code has very little useful comments, and it'll likely The existing code has very little useful comments, and it'll likely
take us years to fix it. Please don't make it harder than it already take us years to fix it. Please don't make it harder than it already