This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-release.git
The following commit(s) were added to refs/heads/main by this push:
new 3a3cf31 Add a convention about functions with linear flow
3a3cf31 is described below
commit 3a3cf3134a8c34d592339827125395c83d8c9ebb
Author: Sean B. Palmer <[email protected]>
AuthorDate: Thu May 22 15:41:02 2025 +0100
Add a convention about functions with linear flow
---
docs/conventions.html | 10 ++++++++++
docs/conventions.md | 15 +++++++++++++++
2 files changed, 25 insertions(+)
diff --git a/docs/conventions.html b/docs/conventions.html
index 84997b1..fa576e8 100644
--- a/docs/conventions.html
+++ b/docs/conventions.html
@@ -119,6 +119,16 @@ def license_files_verify(): # sorted alphabetically
<p>Note how verbs tend to come last, so that function names now read in an
object oriented style, like a module, object, and action.</p>
<p>While this approach can lead to slightly longer function names, the
benefits of improved code organisation and discoverability outweigh the
verbosity.</p>
<p>Classes should always be placed before functions. Private, underscored,
classes should be placed after all public classes, and likewise for
functions.</p>
+<h3>Use numbers in function names with long, linear flow</h3>
+<p>In some cases, such as testing, computation proceeds through a predictable,
linear path and is implemented across many functions. In such cases, use
numbers in the function names to make the order clear. One disadvantage to this
style is the requirement to renumber all subsequent functions when inserting a
new function in the middle.</p>
+<p><strong>Example:</strong></p>
+<pre><code class="language-python">def example_01_start():
+def example_02_prepare():
+def example_03_query():
+def example_04_filter():
+def example_05_process()):
+def example_06_clean_up():
+</code></pre>
<h3>Give helper functions the same prefix as their parent function</h3>
<p>This makes it easier to find all the functions related to a specific
task.</p>
<p><strong>Example</strong>:</p>
diff --git a/docs/conventions.md b/docs/conventions.md
index b5eadec..b14c911 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -185,6 +185,21 @@ While this approach can lead to slightly longer function
names, the benefits of
Classes should always be placed before functions. Private, underscored,
classes should be placed after all public classes, and likewise for functions.
+### Use numbers in function names with long, linear flow
+
+In some cases, such as testing, computation proceeds through a predictable,
linear path and is implemented across many functions. In such cases, use
numbers in the function names to make the order clear. One disadvantage to this
style is the requirement to renumber all subsequent functions when inserting a
new function in the middle.
+
+**Example:**
+
+```python
+def example_01_start():
+def example_02_prepare():
+def example_03_query():
+def example_04_filter():
+def example_05_process()):
+def example_06_clean_up():
+```
+
### Give helper functions the same prefix as their parent function
This makes it easier to find all the functions related to a specific task.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
