update style guideline to reflect current practice

It now mentions clang-format, doesn't parenthesize return values,
and no longer calls for backward compatibility in public function names.

doc/dev/style.md

@@ -31,6 +31,15 @@ all supported platforms that don't support all of the C11 features.
 Given a reasonable set of things to warn about (e.g. -W -Wall for gcc), the goal
 is to compile with no warnings.
 
+#### Automatic style enforcement
+
+All code merged into BIND 9 is checked first with the most recent
+stable version of clang-format, using the settings defined in the files
+.clang-format and .clang-format.headers at the top of the source tree.
+It can reformat code as needed to follow most of the style guidelines
+described below, except in cases where human judgment is required,
+such as choice of variable names.
+
 #### Copyright Notices
 
 The license described in the ``COPYING`` file applies to the BIND 9 source as a
@@ -266,8 +275,7 @@ The use of ANSI C function prototypes is required.
 
 The return type of the function should be listed on a line by itself when
 specifying the implementation of the function.  The opening curly brace
-should occur on the same line as the argument list, unless the argument
-list is more than one line long:
+should occur on the same line as the argument list:
 
         static void
         func1(int i) {
@@ -276,8 +284,7 @@ list is more than one line long:
 
         int
         func2(int first_argument, int next_argument,
-    	      int last_argument)
-    	{
+              int last_argument) {
                 /* whatever */
         }
 
@@ -341,7 +348,7 @@ Bad:
 * DO put a space after `,`.
 * DO put a space after `;` in a `for` statement.
 * DO put spaces after C reserved words such as `if`, `for`, `while`, and `do`.
-* DO put a space after `return`, and parenthesize the return value.
+* DO put a space between `return` and the return value, if any.
 * Do NOT put a space between a variable or function name and `(` or `[`.
 * Do NOT put a space after the `sizeof` operator name, and DO parenthesize its argument: `malloc(4 * sizeof(long))`.
 * Do NOT put a space immediately after a `(` or immediately before a `)`, unless it improves readability.  The same goes for `[` and `]`.
@@ -533,11 +540,11 @@ Good:
 
     Okay:
 
-    	return ((length1 < length2) ? -1 : 1);
+        return (length1 < length2) ? -1 : 1;
 
     Bad:
 
-    	return (success ? ISC_R_SUCCESS : ISC_R_FAILURE);
+        return success ? ISC_R_SUCCESS : ISC_R_FAILURE;
 
 #### Assignment in Parameters
 
@@ -599,7 +606,7 @@ Bad:
                         while (j < 10) ++j;
                 }
                 [...] /* j not used here */
-    		return (0);
+                return 0;
         }
 
 Good:
@@ -727,35 +734,16 @@ separating natural word elements, as demonstrated in
 `isc_commandline_argument` and `dns_name_setbuffer` above.  The `{module}`
 part is usually the same as the basename of the source file, but sometimes
 other `{module}` interfaces appear within one file, such as `dns_label_*`
-interfaces in `lib/dns/name.c`.  However, in the public libraries the file
-name must be the same as some module interface provided by the file; e.g.,
-`dns_rbt_*` interfaces would not be declared in a file named redblack.c (in
-lieu of any other `dns_redblack_*` interfaces in the file).
+interfaces in `lib/dns/name.c`.  But generally, the file name must be
+the same as some module interface provided by the file; e.g., `dns_rbt_*`
+interfaces would not be declared in a file named redblack.c (in lieu of any
+other `dns_redblack_*` interfaces in the file).
 
 The one notable exception to this naming rule is the interfaces provided by
 `<isc/util.h>`.  There's a large caveat associated with the public
 description of this file that it is hazardous to use because it pollutes
 the general namespace.
 
-When the signature of a public function needs to change, the old function
-name should be retained for backward compatibility, if at all possible.
-For example, when `dns_zone_setfile()` needed to include a file format
-parameter, it was changed to `dns_zone_setfile2()`; the original function
-name became a wrapper for the new function, calling it with the default
-value of the format parameter:
-
-    	isc_result_t
-    	dns_zone_setfile(dns_zone_t *zone, const char *file) {
-    		return (dns_zone_setfile2(zone, file, dns_masterformat_text);
-    	}
-
-    	isc_result_t
-    	dns_zone_setfile2(dns_zone_t *zone, const char *file,
-    			  dns_masterformat_t format)
-    	{
-    		...
-    	}
-
 #### <a name="private_namespace"></a>Shared Private Interfaces
 
 When a module provides an interface for internal use by other modules in