Skip to content

Guideline for scripts

Jump to bottom
adrianbartyczak edited this page Dec 7, 2017 · 21 revisions

Guideline for scripts in Shell.

  1. General
  2. Format
  3. Code style

General

A script ...

  • is commented.
  • fully complies with the don't repeat yourself (DRY) principle.
  • may provide a small supplementary feature (example: getmobiletappos).
  • uses a generic name.

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
# 
# Supplementary feature
# 
# 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
  • 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.

Bash

Variables
  • A non-global variable inside a function is declared local.
  • An argument variable is called with brackets (e.g. ${var}, not $var).
  • A user-defined variable is called with brackets (e.g. ${var}, not $var).
Functions
  • A function name uses camel casing.
Output and redirection
  • An error message is redirected to stderr with 1>&2.
Other
  • A non-zero exit code is returned when exiting due to an error.

All other code style rules are up to the contributor.

Clone this wiki locally