Differences

This shows you the differences between two versions of the page.

--- file_naming_conventions [2026-03-10 06:43 pm] – created hcho
+++ file_naming_conventions [2026-03-10 07:23 pm] (current) – hcho
@@ Line 1: / Line 1: @@
 ====== File naming conventions ======
-This page defines the file naming conventions used in lab repositories.
+This page defines the filename and directory naming conventions used in lab repositories. These conventions apply to new repositories and new files. Existing repositories are not retroactively renamed unless there is a strong practical reason to do so.
 ===== General principles =====
-  * Use descriptive filenames.
+  * Use descriptive names.
-  * Avoid spaces in filenames.
+  * Use only lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (_).
-  * Use lowercase letters.
+  * Avoid spaces and other special characters.
-  * Separate words consistently using hyphens or underscores depending on context.
+  * Use **hyphens (-)** by default.
+  * Use **underscores (_)** only for software source code files.
 ===== Documentation and manuscripts =====
-Documentation files, manuscripts, figures, tables, and other human-readable artifacts use **hyphens** to separate words.
+Documentation files, manuscripts, figures, tables, LaTeX macros, and other document-related files use **hyphens** to separate words.
 Examples:
+  main.tex
   cover-letter.tex
   cover-letter.pdf
   review-response.tex
-  review-response.pdf
+  response-macros.tex
   fig-study-basin.tex
-  fig-study-basin.pdf
   tab-algorithms.tex
-  submission-docs/
+  software-availability.tex
-Hyphens improve readability and match conventions commonly used in documentation and URLs.
+Hyphens improve readability and match conventions commonly used in documentation, URLs, and open-source repositories.
-===== Source code =====
+===== Command-line tools =====
-Source code files use **underscores** to separate words.
+Command-line interface (CLI) programs use **hyphens** in executable names because they are user-facing commands.
+Examples:
+  flow-direction
+  longest-flow-path
+  mesh-builder
+===== Workflow scripts =====
+Workflow scripts are treated as command-line tools and therefore also use **hyphens**.
+If the execution order matters, a numeric prefix may be used.
+Examples:
+-download-files.sh
+-preprocess-files.sh
+-run-model.sh
+-postprocess-results.sh
+===== Software source code =====
+Software source code files use **underscores** to separate words. This ensures compatibility with programming identifiers and module imports.
 Examples:
@@ Line 38: / Line 62: @@
   grid_utils.h
-Underscores are preferred because they are compatible with programming identifiers and module imports.
+===== Directory names =====
+Directory names use **hyphens**, unless the directory represents a software package that must follow programming naming rules.
+Examples:
+  submission-docs/
+  review-response/
+  fig-study-area/
+  build-scripts/
 ===== Generated files =====
@@ Line 47: / Line 80: @@
   cover-letter.tex → cover-letter.pdf
-This avoids unnecessary renaming during the build process.
-===== Exceptions =====
-Some ecosystems have their own naming conventions and should follow those conventions. For example, GRASS modules follow the GRASS naming scheme.