Differences

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

--- file_naming_conventions [2026-03-10 07:03 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 filename and directory 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 names.
-  * Avoid spaces in filenames and directory names.
+  * Use only lowercase letters (a-z), digits (0-9), hyphens (-), and underscores (_).
-  * Use lowercase letters.
+  * Avoid spaces and other special characters.
-  * Use **hyphens (-)** by default.
+  * Use **hyphens (-)** for named entities intended primarily for human reading and reference.
-  * Use **underscores (_)** only for software source code files.
+  * 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 =====
@@ Line 27: / Line 38: @@
 Hyphens improve readability and match conventions commonly used in documentation, URLs, and open-source repositories.
+===== 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
 ===== Command-line tools =====
@@ Line 49: / Line 73: @@
   grid_utils.h
-===== Directory names =====
+===== GIS datasets and technical identifiers =====
-Directory names use **hyphens**, unless the directory represents a software package that must follow programming naming rules.
+GIS datasets and technical identifiers use **underscores** to separate words. This ensures compatibility with GIS layers, raster algebra, databases, and similar computational environments.
 Examples:
-  submission-docs/
+  gcn10_amc_i.tif
-  review-response/
+  gcn10_amc_ii.tif
-  fig-study-area/
+  nm_hydro_basins.gpkg
-  build-scripts/
+  stream_order.parquet
 ===== Generated files =====