Skip to content

Guideline for scripts

Jump to bottom
adrianbartyczak edited this page Mar 15, 2019 · 21 revisions

Guideline for scripts in Gnu-linux-shell-use.

  1. General
  2. Format
  3. Code style

General

A script ...

  • is commented.
  • fully complies with the don't repeat yourself (DRY) principle.
  • may provide up to one small supplemental feature (example: watchandroiddevscreentappos).
  • uses a generic name.

Format

Documentation

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

#!/usr/bin/env <language>
# 
# File:
#   file name
# 
# Description:
#   description
# 
# Supplemental feature:
#   supplemental feature
# 
# Usage:
#   file_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 shown here is included if necessary.
  • If a script provides help documentation, information in it is not duplicated in the script's documentation (with the exception of the solution name and 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 "\
File

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 not shown here 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 execinnewterm and findfileforcmd.

Code style

General

Lines and indentation
  • A line is a maximum length 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, windTitle, archFrmt, not currentDirectoryPath, windowTitle, archiveFormat). A noun in a variable is abbreviated to exactly 4 characters when possible and if the abbreviation makes sense (e.g. currDirPath not currDircPath). A 5 character long noun in a variable is not abbrevaited.

  • A non-noun word in a variable is preferrably abbreivated to exactly 4 characters when possible and if the abbreviation makes sense but is abbreviated to only at least 3 characters.

  • A global variable is fully capitalized.

  • All words in a global variable are not abbreviated.

Bash

Variables
  • A non-global variable inside a function is declared local.
  • An argument (e.g. $1 and $2) and 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 developer.

Clone this wiki locally