From e1ab203cad3eaec4852f83c6088598c53bc43d55 Mon Sep 17 00:00:00 2001
From: Johnathan Van Why <jrvanwhy@google.com>
Date: Tue, 22 Aug 2023 12:10:07 -0700
Subject: [PATCH] Coding style: add a section on list ordering.

I've been keeping a lot of things (such as `Cargo.toml` package lists and `mod` declarations) in alphabetical order. This adds that preference to the style guide, so other contributors are aware of it.
---
 Cargo.toml   | 12 ++++++------
 doc/Style.md | 15 +++++++++++++++
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 1ae3b4cc..5eaaa39f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -32,14 +32,14 @@ libtock_temperature = { path = "apis/temperature" }
 libtock_build_scripts = { path = "build_scripts"}
 
 [profile.dev]
-panic = "abort"
-lto = true
 debug = true
+lto = true
+panic = "abort"
 
 [profile.release]
-panic = "abort"
-lto = true
 debug = true
+lto = true
+panic = "abort"
 
 [workspace]
 exclude = ["tock"]
@@ -47,16 +47,16 @@ members = [
     "apis/adc",
     "apis/air_quality",
     "apis/alarm",
-    "apis/gpio",
+    "apis/ambient_light",
     "apis/buttons",
     "apis/buzzer",
     "apis/console",
+    "apis/gpio",
     "apis/leds",
     "apis/low_level_debug",
     "apis/ninedof",
     "apis/proximity",
     "apis/temperature",
-    "apis/ambient_light",
     "panic_handlers/debug_panic",
     "panic_handlers/small_panic",
     "platform",
diff --git a/doc/Style.md b/doc/Style.md
index c973c97b..49e8c82d 100644
--- a/doc/Style.md
+++ b/doc/Style.md
@@ -1,6 +1,21 @@
 Coding Style
 ============
 
+## List Ordering
+
+Source code tends to contain many lists whose order is unimportant, such as
+dependency lists in `Cargo.toml` and `mod` declarations in `.rs` files. When
+there isn't a better reason to prefer a particular order, these lists should be
+in alphabetical order.
+
+Benefits:
+
+1. When lists become long, this makes it easier to search for a particular
+   entry.
+2. Always adding new entries at the bottom of the list results in merge
+   conflicts whenever two PRs add entries to the same list. Putting them in
+   alphabetical order decreases the probability of merge conflicts.
+
 ## Naming Conventions
 
 Many things in `libtock-rs` live outside Rust's namespacing system, and can