From 52a797bfe5ced4329f2272be417c35730ec8839f Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Tue, 22 Feb 2022 15:21:11 +0200
Subject: doc: Avoid ADL for function calls

---
 doc/developer-notes.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'doc/developer-notes.md')

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index bfb64093e1..4cee70863b 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -105,6 +105,28 @@ code.
   - `nullptr` is preferred over `NULL` or `(void*)0`.
   - `static_assert` is preferred over `assert` where possible. Generally; compile-time checking is preferred over run-time checking.
 
+For function calls a namespace should be specified explicitly, unless such functions have been declared within it.
+Otherwise, [argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl), also known as ADL, could be
+triggered that makes code harder to maintain and reason about:
+```c++
+#include <filesystem>
+
+namespace fs {
+class path : public std::filesystem::path
+{
+};
+// The intention is to disallow this function.
+bool exists(const fs::path& p) = delete;
+} // namespace fs
+
+int main()
+{
+    //fs::path p; // error
+    std::filesystem::path p; // compiled
+    exists(p); // ADL being used for unqualified name lookup
+}
+```
+
 Block style example:
 ```c++
 int g_count = 0;
-- 
cgit v1.2.3