Proposals

Bash Variable Naming Proposal

Draft

Introduction

Bash scripting is widely used for automation, system management, and small utilities. While some comprehensive style-guides exist, there is little formal guidance for variable naming, which is important for readability and maintainability.

This document proposes a consistent convention for Bash variable names, covering constants, environment variables, global variables, local variables, arrays, and practical examples to improve clarity, reduce errors, and facilitate collaboration.

1. Global vs. Local

Any variable in Bash is global by default, regardless of being defined inside or outside a function. Only variables declared with the local keyword are detached from the global scope. The local keyword can only be used inside functions.

Examples:

function test_local {
  local var=a                      # Local variable.
  echo "Inside function:"
  echo "var = ${var}"
}

var=1
echo "var = ${var}"

test_local

echo "outside function:"
echo "var = ${var}"

Result:

var = 1
Inside function:
var = a
outside function:
var = 1

2. Uppercase vs. Lowercase

Use UPPERCASE for any variable with a global scope and whose value does not change during script execution.

The rule is simple:

Always use uppercase for:

Global variables with static content
Exported variables

The common denominator is that these variables are global and not meant to be changed, hence static. Place such variables at the top of the script, or in a dedicated configuration section or function.

For any other variable, use lowercase.

Examples

IFNAMSIZ=16                        # Constant limiting iface name length.
BD=$'\e[1m'                        # Global terminal escape sequence for bold text.
IAM=${BASH_SOURCE[0]##*/}          # Fixed script name, global.
export WKDIR=/tmp                  # Global variable $WKDIR including sub-shells.
declare -r MAX_TRIES=5             # Global read-only variable.

3. Global Variables

Use lowercase names with a _0 suffix for global variables not predicted to remain static.

Examples

num_tries_0=10                # Total number of tries applying globally.
debug_0=on                    # Switch debug on or off on demand.
status_0="in progress"        # Current status, available globally.
declare -a info_array_0=()    # Global array variable, update on demand.

4. Local Variables

Use lowercase names for variables that are temporary or valid only within a function. Temporary variables are typically loop counters or variables used to store intermediate results inside a block of code.

Examples

a=( 'BD:bold' 'C1:setaf 1' 'RG:bel' 'T0:sgr0' )            # Helper array $a.
for i in "${a[@]}"; do                                     # Temporary loop variable $i.
  printf -v "${i%:*}" '%s' "$(tput ${i#*:} 2>/dev/null)"   # Create temporary variables
  export ${i%:*}                                           # and export them as globals.
done
echo ${RG}bell

get_random() {
  local rand=$(mktemp -u XXXXXX)                           # Local temporary variable.
  echo "${rand}"
}

5. Decision Process

Although deciding the correct variable naming style may seem complex at first, applying the rule is just a matter of asking two simple questions

Is the variable used only within the next block of code?
   ┃
   ├─ Yes → lowercase (local, intermediate, temporary, etc.)
   ┃
   └─ No → Is the value static or read-only?
       │
       ├─ Yes → UPPERCASE (global, static)
       │
       └─ No → lowercase + _0 suffix (global, mutable)

Examples

project_dir="$HOME/maxJOT"                         # Intermediate
date_tag=$(date +%d-%b-%y)   # e.g., 15-Dec-25     # Temporary
UI_DIR="${project_dir}/ui/${date_tag}"             # Global (static)

6. Variable Naming Chart

The following chart provides an overview of common variable categories for readers already familiar with Bash.

Type Scope & Usage Naming Convention Example

Type	Scope & Usage	Naming Convention	Example
Constants, Env, Global variables (fixed)	Script-wide	UPPERCASE	RG, IFNAMSIZ, IAM
Global variables	Script-wide	lowercase + `_0`	info_array_0, debug_0
Local variables (function)	Detached from global scope	lowercase	rand
Temporary variables	Intermediate, counters	lowercase	i, a[i]

Constants, Env, Global variables (fixed)

Script-wide

UPPERCASE

RG, IFNAMSIZ, IAM

Global variables

Script-wide

lowercase + _0

info_array_0, debug_0

Local variables (function)

Detached from global scope

lowercase

rand

Temporary variables

Intermediate, counters

lowercase

i, a[i]

7. Benefits

This standard emphasizes clarity, maintainability, and scope awareness.
Compatible with complex and large Bash scripts.
Intended as an easy to comprehend and adoptable standard.