From 1499363d85abedbdb571e33801b821f4dfabc638 Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Fri, 22 Nov 2024 17:28:28 +0100
Subject: more documentation

---
 contributing.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

(limited to 'contributing.md')

diff --git a/contributing.md b/contributing.md
index 77a2908..0a90e86 100644
--- a/contributing.md
+++ b/contributing.md
@@ -17,6 +17,7 @@ that you can click on to open them.
   working/compiling version of the project
 - Pull requests for new code include either automated tests for the new code or
   an explanation as to why the code can not (reliably) be tested
+
 <!--
 - TODO: tagging / versions
 -->
@@ -495,6 +496,12 @@ that you can click on to open them.
   </td></tr></table></details>
 - <details><summary>
   Ensure const-correctness
+
+  > [!IMPORTANT]
+  > C-style APIs that work on (possibly internal) references to structs can be
+  > called from const member functions in C++. If the compiler allows you to
+  > mark a function as `const` even though it has side effects, it should
+  > **not** be marked as `const`.
   </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td>
 
   ```cpp
@@ -795,6 +802,23 @@ that you can click on to open them.
   ```
   </td></tr></table></details>
 - Do not implement new classes as singletons
+- <details><summary>
+  Retrieving the first or last indices for iterators with a known or expected
+  size should be done using <code>.front()</code> or <code>.back()</code>
+  instead of by index
+  </summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td>
+
+  ```cpp
+  vector<int> foo = { 1, 2, 3 };
+  int bar = foo.first();
+  ```
+  </td><td>
+
+  ```cpp
+  vector<int> foo = { 1, 2, 3 };
+  int bar = foo[0];
+  ```
+  </td></tr></table></details>
 
 ## CMakeLists-specific
 
-- 
cgit v1.2.3