Skip to content

Guideline for scripts

Jump to bottom
linux-shell-base edited this page Oct 18, 2017 · 21 revisions

Guideline for scripts in Linux-shell-base.

  1. General
  2. Format
  3. Code style

General

A script ...

  • is commented.
  • fully complies with the don't repeat yourself (DRY) principle.

A comment ...

  • states the reason a piece of code exists rather than what it does (with exceptions).

Code blocks ...

  • that do significantly different tasks are separated by a blank line.

Format

Documentation

A script is documented in the following format:
(Note: Any section after Description is included only when necessary)

#!/usr/bin/env <language>
# 
# Description
# 
# Additional features
# 
# Usage:
#   script_name usage
# 
# Options:
#   -?     option description (all lowercase characters)
#   --?    option description (all lowercase characters)
#   --?, -?    option description (all lowercase characters)
#   ...
# 
# Examples:
#   # example 1 description (all lowercase characters)
#   example 1
# 
#   # example 2 description (all lowercase characters)
#   example 1
# 
#   ...
# 
# Returns:
#   Description of return value(s)
# 
# Exit Codes:
#   0: Description
#   1: Description
#   ...
# 
# Dependencies:
#   dependency 1 [(reason/purpose/info)]
#   dependency 2 [(reason/purpose/info)]
#   ...
# 
# Source(s):
#   URL 1
#   URL 2
#   ...
# 
# Note(s):
#   Note 1
#   Note 1 continued
# 
#   Note 2
#   Note 2 continued
#   Note 2 continued
# 
#   ...
#
  • Any other section not listed here is included when necessary.
  • If a script provides help documentation, information in it is not duplicated in the script's documentation (with the exception of the description).

Primary global statements and configuration variables

Primary global statements (e.g. main script variable assignments, sourced files, included libraries) are placed right after the documentation. Configuration variables are placed after them and contained in a CONFIGURATIONS section:

#!/usr/bin/env <language>
# 
# ... documentation ...
# 

source SCRIPT.sh
readonly GLOBAL_VAR_1='<VALUE>' | my $GLOBAL_VAR_1 = '<VALUE>' | etc.
readonly GLOBAL_VAR_2='<VALUE>' | my $GLOBAL_VAR_2 = '<VALUE>' | etc.
...

# ======= CONFIGURATIONS ==============

# Description
readonly CONFIG_VAR_1='<VALUE>' | my $CONFIG_VAR_1 = '<VALUE>' | etc.

# Description
readonly CONFIG_VAR_2='<VALUE>' | my $CONFIG_VAR_2 = '<VALUE>' | etc.

# Description
CONFIG_FUNCTION() {
  ... function code ...
}

...

# ======= ! CONFIGURATIONS ==============

... beginning of script's main code ...

Help documentation

If a script provides help documentation, it is placed in a function right after the CONFIGURATIONS section or primary global statements if it does not exist. It is formatted the same as script documentation for easy readability:

... primary global statements and/or configuration variables ...

pintHelpMessage() {
  echo -ne "\
Description

Usage:
  script_name usage

Options:
  -?     option description (all lowercase characters)
  --?    option description (all lowercase characters)
  --?, -?    option description (all lowercase characters)
  ...

Examples:
  # example 1 description (all lowercase characters)
  example 1

  # example 2 description (all lowercase characters)
  example 1

  ...

Note(s):
  Note 1
  Note 1 continued

  Note 2
  Note 2 continued
  Note 2 continued

  ...
"
}

... script's main code continued ...
  • Any other section is included if necessary.

Code sections

Code is sectioned using a comment block in the following format:

... section end ...

# ============================================
#   New section name
# ============================================

... section start ...

For examples, see newterm and returnfileforcmd

Code style

General

Lines and indentation
  • Spaces are used for all whitespace (tabs are allowed for Bash Here documents only).
  • An indent is 2 spaces.
  • A line is a maximum width of 80 characters.
  • A line is continued on the next line only with the last (space separated) word that exceeds the 80 character limit.
  • A continued line is indented 4 spaces from its beginning column.
Variables
  • A variable name uses abbreviated words except when it makes sense to use full words (e.g. currDirPath, windTtl, archvFrmt, not currentDirectoryPath, windowTitle, archiveFormat). One should, however, always be at least 4 characters long when possible.
  • A constant variable is all uppercase letters.
Strings
  • Single quotes are used when possible.

Bash

Variables
  • A variable is called with brackets (e.g. ${var}, not $var); this is optional for bash default non-argument variables (e.g. $#, $? and $!).
  • A non-global variable inside a function is declared local.
  • A variable in an arithmetic expression is called without brackets (e.g. $((numEntries - count)), not $((${numEntries} - ${count}))).
  • An argument variable (e.g. ${1}) is used directly rather than being assigned to a new variable when possible.
Functions
  • A function name uses camel casing.
Conditionals
  • A single bracket conditional is used when possible.
Output and redirection
  • An error message is redirected to stderr with 1>&2.
Other
  • A parameter expansion or command substitution is quoted unless otherwise required.
  • A case block is used when matching 3 or more values.
  • A non-zero exit code is returned when exiting due to an error.

Perl

Variables
  • A variable does not use brackets (e.g. $var, not ${var}) except when it makes sense to (e.g. in regular expressions and large scopes).
Strings
  • A string value containing variables uses double quotes around the constant strings and variables.
Other
  • Parentheses are used when calling non-standard functions.

All other code style rules are up to the user. Contributions will be reviewed.

Clone this wiki locally