Differences

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

--- file_naming_conventions [2026-03-10 06:45 pm] – hcho
+++ file_naming_conventions [2026-05-31 06:21 pm] (current) – [Technical identifiers] hcho
@@ Line 1: / Line 1: @@
 ====== File naming conventions ======
-This page defines the file naming conventions used in this repository.
+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 (-)** for named entities intended primarily for human reading and reference.
+  * Use **underscores (_)** for technical identifiers intended primarily for software, programming languages, databases, GIS, and other computational environments.
+===== 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/
 ===== 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, URLs, and open-source repositories.
-===== Source code =====
+===== Workflow scripts =====
-Source code files use **underscores** to separate words.
+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:
-  flow_direction.py
+-download-files.sh
-  longest_flow_path.py
+-preprocess-files.sh
-  mesh_builder.cpp
+-run-model.sh
-  grid_utils.h
+-postprocess-results.sh
-Underscores are preferred because they are compatible with programming identifiers and module imports.
 ===== Command-line tools =====
-Command-line interface (CLI) programs use **hyphens** in their executable names because they are user-facing commands.
+Command-line interface (CLI) programs use **hyphens** in executable names because they are user-facing commands.
 Examples:
@@ Line 50: / Line 62: @@
   mesh-builder
-Hyphenated command names improve readability and are consistent with common Unix command naming practices.
+===== Software source code =====
+Software source code files use **underscores** to separate words. This ensures compatibility with programming identifiers and module imports.
+Examples:
+  flow_direction.py
+  longest_flow_path.py
+  mesh_builder.cpp
+  grid_utils.h
+===== GIS datasets and technical identifiers =====
+GIS datasets and technical identifiers use **underscores** to separate words. This ensures compatibility with GIS layers, raster algebra, databases, and similar computational environments.
+Examples:
+  gcn10_amc_i.tif
+  gcn10_amc_ii.tif
+  nm_hydro_basins.gpkg
+  stream_order.parquet
 ===== Generated files =====
@@ Line 59: / Line 91: @@
   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.