From: Daniel Stenberg <daniel@haxx.se>
Date: Sun, 16 Feb 2025 13:50:45 +0000 (+0100)
Subject: CODE_STYLE: readability and banned functions
X-Git-Tag: curl-8_13_0~460
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=37128035e55dabd685c5865648a567c1c06e99e7;p=thirdparty%2Fcurl.git

CODE_STYLE: readability and banned functions

Closes #16349
---

diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words
index 1961715516..728ba8d3f4 100644
--- a/.github/scripts/spellcheck.words
+++ b/.github/scripts/spellcheck.words
@@ -253,6 +253,7 @@ filesize
 filesystem
 FLOSS
 fnmatch
+footguns
 formpost
 formposts
 Fortnite
diff --git a/docs/internals/CODE_STYLE.md b/docs/internals/CODE_STYLE.md
index f64c5eb7d4..f908bf927b 100644
--- a/docs/internals/CODE_STYLE.md
+++ b/docs/internals/CODE_STYLE.md
@@ -27,6 +27,14 @@ We also work hard on writing code that are warning-free on all the major
 platforms and in general on as many platforms as possible. Code that obviously
 causes warnings is not accepted as-is.
 
+## Readability
+
+A primary characteristic for code is readability. The intent and meaning of
+the code should be visible to the reader. Being clear and unambiguous beats
+being clever and saving two lines of code. Write simple code. You and others
+who come back to this code over the coming decades want to be able to quickly
+understand it when debugging.
+
 ## Naming
 
 Try using a non-confusing naming scheme for your new functions and variable
@@ -314,3 +322,42 @@ typedef struct {
 } something;
 something instance;
 ```
+
+## Banned functions
+
+To avoid footguns and unintended consequences we forbid the use of a number of
+C functions. The `checksrc` script finds and yells about them if used. This
+makes us write better code.
+
+This is the full list of functions generally banned.
+
+    _access
+    _mbscat
+    _mbsncat
+    _tcscat
+    _tcsncat
+    _waccess
+    _wcscat
+    _wcsncat
+    access
+    gets
+    gmtime
+    LoadLibrary
+    LoadLibraryA
+    LoadLibraryEx
+    LoadLibraryExA
+    LoadLibraryExW
+    LoadLibraryW
+    localtime
+    snprintf
+    sprintf
+    sscanf
+    strcat
+    strerror
+    strncat
+    strncpy
+    strtok
+    strtol
+    strtoul
+    vsnprint
+    vsprintf