[tor-commits] [tor/master] Fold remainder of this-not-that.md into CodingStandards.md

[nickm at torproject.org]

commit f221a7aaf6f05670f0d19f66c792d3b96f385f43
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Nov 12 12:28:14 2019 -0500

    Fold remainder of this-not-that.md into CodingStandards.md
---
 doc/HACKING/CodingStandards.md      | 30 +++++++++++++++++-----
 doc/HACKING/design/this-not-that.md | 51 -------------------------------------
 2 files changed, 24 insertions(+), 57 deletions(-)

diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index 966a2b810..34d1dd52b 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -212,7 +212,8 @@ deviations from our C whitespace style.  Generally, we use:
    - No space between a function name and an opening paren. `puts(x)`, not
      `puts (x)`.
    - Function declarations at the start of the line.
-   - Use `void foo(void)` to declare a function with no arguments.
+   - Use `void foo(void)` to declare a function with no arguments.  Saying
+     `void foo()` is C++ syntax.
    - Use `const` for new APIs.
 
 If you use an editor that has plugins for editorconfig.org, the file
@@ -230,22 +231,32 @@ We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and
 `tor_gettimeofday;` use them instead of their generic equivalents.  (They
 always succeed or exit.)
 
+Specifically, Don't use `malloc`, `realloc`, `calloc`, `free`, or
+`strdup`. Use `tor_malloc`, `tor_realloc`, `tor_calloc`, `tor_free`, or
+`tor_strdup`.
+
+Don't use `tor_realloc(x, y\*z)`. Use `tor_reallocarray(x, y, z)` instead.;
+
 You can get a full list of the compatibility functions that Tor provides by
 looking through `src/lib/*/*.h`.  You can see the
 available containers in `src/lib/containers/*.h`.  You should probably
 familiarize yourself with these modules before you write too much code, or
 else you'll wind up reinventing the wheel.
 
-We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously broken
-old C functions.  Use `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead.
+
+We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously
+broken old C functions.  We also avoid `strncat` and `strncpy`. Use
+`strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead.
 
 We don't call `memcmp()` directly.  Use `fast_memeq()`, `fast_memneq()`,
-`tor_memeq()`, or `tor_memneq()` for most purposes.
+`tor_memeq()`, or `tor_memneq()` for most purposes.  If you really need a
+tristate return value, use `tor_memcmp()` or `fast_memcmp()`.
 
 Don't call `assert()` directly. For hard asserts, use `tor_assert()`. For
 soft asserts, use `tor_assert_nonfatal()` or `BUG()`. If you need to print
 debug information in assert error message, consider using `tor_assertf()` and
-`tor_assertf_nonfatal()`.
+`tor_assertf_nonfatal()`.  If you are writing code that is too low-level to
+use the logging subsystem, use `raw_assert()`.
 
 Don't use `toupper()` and `tolower()` functions. Use `TOR_TOUPPER` and
 `TOR_TOLOWER` macros instead. Similarly, use `TOR_ISALPHA`, `TOR_ISALNUM` et.
@@ -258,6 +269,12 @@ Avoid calling BSD socket functions directly. Use portable wrappers to work
 with sockets and socket addresses. Also, sockets should be of type
 `tor_socket_t`.
 
+Don't use any of these functions: they aren't portable. Use the
+version prefixed with `tor_` instead: strtok_r, memmem, memstr,
+asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton,
+getpass, ntohll, htonll.  (This list is incomplete.)
+
+
 What code can use what other code?
 ----------------------------------
 
@@ -350,7 +367,8 @@ Binary data and wire formats
 ----------------------------
 
 Use pointer to `char` when representing NUL-terminated string. To represent
-arbitrary binary data, use pointer to `uint8_t`.
+arbitrary binary data, use pointer to `uint8_t`. (Many older Tor APIs ignore
+this rule.)
 
 Refrain from attempting to encode integers by casting their pointers to byte
 arrays. Use something like `set_uint32()`/`get_uint32()` instead and don't
diff --git a/doc/HACKING/design/this-not-that.md b/doc/HACKING/design/this-not-that.md
deleted file mode 100644
index 815c7b2fb..000000000
--- a/doc/HACKING/design/this-not-that.md
+++ /dev/null
@@ -1,51 +0,0 @@
-
-Don't use memcmp.  Use {tor,fast}_{memeq,memneq,memcmp}.
-
-Don't use assert.  Use tor_assert or tor_assert_nonfatal or BUG.  Prefer
-nonfatal assertions or BUG()s.
-
-Don't use sprintf or snprintf.  Use tor_asprintf or tor_snprintf.
-
-Don't write hand-written binary parsers.  Use trunnel.
-
-Don't use malloc, realloc, calloc, free, strdup, etc. Use tor_malloc,
-tor_realloc, tor_calloc, tor_free, tor_strdup, etc.
-
-Don't use tor_realloc(x, y\*z). Use tor_reallocarray(x, y, z);
-
-Don't say "if (x) foo_free(x)".  Just foo_free(x) and make sure that
-foo_free(NULL) is a no-op.
-
-Don't use toupper or tolower; use TOR_TOUPPER and TOR_TOLOWER.
-
-Don't use isalpha, isalnum, etc.  Instead use TOR_ISALPHA, TOR_ISALNUM, etc.
-
-Don't use strcat, strcpy, strncat, or strncpy. Use strlcat and strlcpy
-instead.
-
-Don't use tor_asprintf then smartlist_add; use smartlist_add_asprintf.
-
-Don't use any of these functions: they aren't portable. Use the
-version prefixed with `tor_` instead: strtok_r, memmem, memstr,
-asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton,
-getpass, ntohll, htonll, strdup,   (This list is incomplete.)
-
-Don't create or close sockets directly. Instead use the wrappers in
-compat.h.
-
-When creating new APIs, only use 'char \*' to represent 'pointer to a
-nul-terminated string'.  Represent 'pointer to a chunk of memory' as
-'uint8_t \*'.  (Many older Tor APIs ignore this rule.)
-
-Don't encode/decode u32, u64, or u16 to byte arrays by casting
-pointers. That can crash if the pointers aren't aligned, and can cause
-endianness problems.  Instead say something more like set_uint32(ptr,
-htonl(foo)) to encode, and ntohl(get_uint32(ptr)) to decode.
-
-Don't declare a 0-argument function with "void foo()".  That's C++
-syntax. In C you say "void foo(void)".
-
-When creating new APIs, use const everywhere you reasonably can.
-
-Sockets should have type tor_socket_t, not int.
-