Coding style/Practices - Revision history

Ghudson: /* Avoiding integer overflows */

2024-09-22T19:21:55Z

‎Avoiding integer overflows

2024-09-22T19:20:46Z

2023-07-22T22:11:23Z

‎Misc. to be sorted

2016-03-10T16:57:01Z

2016-03-07T20:46:30Z

‎Exception Handling

2016-03-07T20:46:19Z

‎Exception Handling

2016-01-12T19:26:24Z

‎Misc. to be sorted

2016-01-11T19:42:37Z

2013-07-16T14:48:27Z

ret instead of retval in example

2012-05-10T14:56:16Z

Use shorter name for return value in exception handling example

@@ Line 127: / Line 127: @@
 <pre>
-/* This is safe. */
+/* This is safe if the invariant current <= len holds. */
 if (offset > len - current)
    return EINVAL;

@@ Line 6: / Line 6: @@
 * Keep track of which pointers are owners and which are aliases; initialize owner pointers to NULL.
 * Avoid creating structure instances containing a mix of owner and alias pointers.
 * Name output variables ending with "_out".  Initialize them at the beginning of a function, then don't touch them until just before successful return.
 * Don't use assignments as truth values except (perhaps) in a while loop.
@@ Line 119: / Line 121: @@
 Following these rules makes it easier to verify that a function contains no memory leaks, no double frees, and no dereferences after frees.  These rules also keep memory management logic out of the core logic of a function, making it easier to understand.
 == Output parameter handling ==

@@ Line 583: / Line 583: @@
 the return type, which will default the return type to int.
-Try to use ANSI C prototype-style function definitions in preference
+Use ANSI C prototype-style function declarations and definitions.  For functions with no parameters, use "(void)" in both the declaration and definition.
 Don't pass or return structures in API functions except by address.

@@ Line 458: / Line 458: @@
 For the krb5 library, the prefix for public global symbols is "krb5_".
-Use "k5_" as a prefix for library internal globals ("krb5int_" is
+Use "k5_" as a prefix for library internal globals.  Avoid using "__"
-also acceptable).  Avoid using "__" in symbol names, as it may confuse
+in symbol names, as it may confuse C++ implementations.  There are
-C++ implementations.  There are admittedly a number of places where we
+admittedly a number of places where we leak thing into the namespace;
-leak thing into the namespace; we should try to fix these.
+we should try to fix these.
 Header files should also not leak symbols.  Usually using the upcased
@@ Line 487: / Line 487: @@
 === Conformance ===
-Existing code conforms somewhat, with some egregious exceptions.  Some functions exceed 500 lines in length.
+Existing code conforms somewhat, with some egregious exceptions.  Some functions exceed 500 lines in length.  Older internal library symbols use "krb5int_" as a prefix instead of "k5_".
 === Rationale ===

@@ Line 72: / Line 72: @@
 ...
     ret = another_function(...);
-    if (retb)
+    if (ret)
         goto cleanup;
 ...

← Older revision		Revision as of 19:26, 12 January 2016
Line 590:		Line 590:
	Don't pass or return structures in API functions except by address.		Don't pass or return structures in API functions except by address.

−	Every function should have block comment preceding it describing
		+	Every function should have a block comment describing briefly in complete sentences what it does, what inputs and outputs it has, and what error codes it can return. It should also describe any unusual aspects of the function. If the function is prototyped in a header file, the block comment should precede the prototype in the header file; otherwise it should precede the function definition.
−	briefly in complete sentences what it does, what inputs and outputs it
−	has, and what error codes it can return. It should also describe any
−	unusual aspects of the function. At some point we will want to put
−	some of this information into a machine-parsable form.

	Strive to make your code capable of compiling using "gcc -Wall		Strive to make your code capable of compiling using "gcc -Wall

@@ Line 16: / Line 16: @@
 * Avoid stepping on reserved C namespaces.
 * Use the krb5_ prefix for libkrb5 API functions, and the k5_ prefix for linker-visible internal functions.  Don't use a prefix for static functions.
 * Avoid long or deeply nested function bodies.  Use helpers to limit function complexity.
 * Function calls through pointers should look like "(*fp)(args)" or "vtable->method(vars)".
@@ Line 516: / Line 518: @@
 Formatting license comments this way allows them to be extracted from source code by scripts, without the need for ugly markers.  The top-level NOTICE file makes it easier to satisfy the documentation requirements of licenses and to determine all of the terms under which MIT Kerberos may be used.
 == Misc. to be sorted ==

@@ Line 165: / Line 165: @@
 <pre>
 /* bad style */
-if ((retval = krb5_foo()))
+if ((ret = krb5_foo()))
     /* ... */;
 </pre>
@@ Line 173: / Line 173: @@
 <pre>
 /* better style */
-retval = krb5_foo();
+ret = krb5_foo();
-if (retval)
+if (ret)
     /* ... */;
 </pre>

@@ Line 64: / Line 64: @@
 <pre>
+{
-    krb5_error_code retval;
+    krb5_error_code ret;
     char *ptr1 = NULL;
     krb5_blah *ptr2 = NULL;
 ...
-    retval = another_function(...);
+    ret = another_function(...);
-    if (retval != 0)
+    if (ret != 0)
         goto cleanup;
 ...
@@ Line 76: / Line 76: @@
     free(ptr1);
     krb5_free_blah(ptr2);
-    return retval;
+    return ret;
+}
 </pre>