aboutsummaryrefslogtreecommitdiff
path: root/Documentation/development-process/4.Coding
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2011-03-25 12:17:53 -0600
committerJonathan Corbet <corbet@lwn.net>2011-03-25 14:30:31 -0600
commit5c050fb96380a87a85aad9084b68fdcd2b84c193 (patch)
treeb1d0bf29716a4e8a0da6d4b9b96bfe9635b58271 /Documentation/development-process/4.Coding
parent9cad7962704d617ab1e4ae304baaaa22d727932b (diff)
docs: update the development process document
Here's a set of changes updating Documentation/development-process. I have update kernel releases and relevant statistics, added information for a couple of tools, zapped some trailing white space, and generally tried to make it more closely match the current state of affairs. [Typo fixes from Joe Perches and Nicolas Kaiser incorporated] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Acked-by: Greg KH <greg@kroah.com> Cc: Randy Dunlap <rdunlap@xenotime.net>
Diffstat (limited to 'Documentation/development-process/4.Coding')
-rw-r--r--Documentation/development-process/4.Coding21
1 files changed, 18 insertions, 3 deletions
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding
index 2278693c8ff..f3f1a469443 100644
--- a/Documentation/development-process/4.Coding
+++ b/Documentation/development-process/4.Coding
@@ -131,6 +131,11 @@ classic time/space tradeoff taught in beginning data structures classes
often does not apply to contemporary hardware. Space *is* time, in that a
larger program will run slower than one which is more compact.
+More recent compilers take an increasingly active role in deciding whether
+a given function should actually be inlined or not. So the liberal
+placement of "inline" keywords may not just be excessive; it could also be
+irrelevant.
+
* Locking
@@ -285,6 +290,13 @@ be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your
distributor does not package it); it can then be run on the code by adding
"C=1" to your make command.
+The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
+variety of potential coding problems; it can also propose fixes for those
+problems. Quite a few "semantic patches" for the kernel have been packaged
+under the scripts/coccinelle directory; running "make coccicheck" will run
+through those semantic patches and report on any problems found. See
+Documentation/coccinelle.txt for more information.
+
Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a
Blackfin development board handy, you can still perform the compilation
@@ -308,7 +320,9 @@ The first piece of documentation for any patch is its associated
changelog. Log entries should describe the problem being solved, the form
of the solution, the people who worked on the patch, any relevant
effects on performance, and anything else that might be needed to
-understand the patch.
+understand the patch. Be sure that the changelog says *why* the patch is
+worth applying; a surprising number of developers fail to provide that
+information.
Any code which adds a new user-space interface - including new sysfs or
/proc files - should include documentation of that interface which enables
@@ -321,7 +335,7 @@ boot-time parameters. Any patch which adds new parameters should add the
appropriate entries to this file.
Any new configuration options must be accompanied by help text which
-clearly explains the options and when the user might want to select them.
+clearly explains the options and when the user might want to select them.
Internal API information for many subsystems is documented by way of
specially-formatted comments; these comments can be extracted and formatted
@@ -372,7 +386,8 @@ which is broken by the change. For a widely-used function, this duty can
lead to literally hundreds or thousands of changes - many of which are
likely to conflict with work being done by other developers. Needless to
say, this can be a large job, so it is best to be sure that the
-justification is solid.
+justification is solid. Note that the Coccinelle tool can help with
+wide-ranging API changes.
When making an incompatible API change, one should, whenever possible,
ensure that code which has not been updated is caught by the compiler.