From b9c13c08b27386e6b6ba984d26845127b7a6012a Mon Sep 17 00:00:00 2001
From: Alexandre Gaigalas <alganet+github@gmail.com>
Date: Sun, 7 Jul 2024 15:30:10 -0300
Subject: [PATCH] Begin a style guide

A style guide is a must for the shell, and the existing ones are
not good enough for us to adopt, since they were not designed with
portability in mind.

We'll begin a new one.
---
 doc/STYLE.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 doc/STYLE.md

diff --git a/doc/STYLE.md b/doc/STYLE.md
new file mode 100644
index 0000000..b10f705
--- /dev/null
+++ b/doc/STYLE.md
@@ -0,0 +1,86 @@
+# coral style guide
+
+### 4-width tab indents
+
+<font color=green>**RIGHT**</font>: Tabs configured to width 4.
+
+<font color=red>**WRONG**</font> Spaces, tabs configured to width different than 4.
+
+_Rationale_: Shell script indented heredocs `<<-` require the use of tabs. Failure to use tabs might yield extra spaces when reading the contents of these structures.
+
+### Space after function name declaration
+
+<font color=green>**RIGHT**</font>: Space between name and `()`
+```sh
+mymod_myfn () {
+    _print hello
+}
+```
+
+<font color=red>**WRONG**</font> No space between name and `()`
+```sh
+mymod_myfn() {
+    _print hello
+}
+```
+
+_Rationale_: However, in sh, we call functions as `foo arg`, not `foo(arg` so we must declare it with an extra space to leverage tools like grep and IDE search.
+
+### No function keyword
+
+<font color=green>**RIGHT**</font>: Space between name and `()`
+```sh
+mymod_myfn () {
+    _print hello
+}
+```
+
+<font color=red>**WRONG**</font> No space between name and `()`
+```sh
+function mymod_myfn {
+    _print hello
+}
+```
+
+_Rationale_: This syntax is not portable.
+
+### No inline functions
+
+<font color=green>**RIGHT**</font>: Function declaration and closing on separated lines
+```sh
+mymod_myfn () {
+    _print hello
+}
+```
+
+<font color=red>**WRONG**</font>: Inlined function
+```sh
+mymod_myfn () { _print hello; }
+```
+
+_Rationale_: Most shells don't support reflection on the currently defined functions. _coral_ uses a shallow parser to perform such reflection once before runtime (for instance, on unit tests). This parser assumes a strict formatting of the source code.
+
+### Functions live at indentation zero
+
+<font color=green>**RIGHT**</font>: Functions are defined on indentation level zero
+```sh
+mymod_myfn () {
+    _print hello
+}
+```
+
+<font color=orange>**OK**</font>: Declaration is on its own line and at indentation zero.
+```sh
+mymod_myfn () {
+        _print hello; }
+```
+
+<font color=red>**WRONG**</font>: Indented function declaration
+```sh
+    mymod_myfn () {
+        _print hello
+    }
+```
+
+_Rationale_: Most shells don't support reflection on the currently defined functions. _coral_ uses a shallow parser to perform such reflection once before runtime (for instance, on unit tests). This parser assumes a strict formatting of the source code.
+