Skip to content

Guideline for scripts

Jump to bottom
adrianbartyczak edited this page Jan 25, 2018 · 21 revisions

Guideline for scripts in General-purpose-computing.

  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 additional feature (example: getmobilescreentappos.
  • 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 if necessary)

#!/usr/bin/env <language>
# 
# File:
#   file name
# 
# Description:
#   description
# 
# Additional feature:
#   additional 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 documentation section not shown 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 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 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. currDirctryPath, windTitle, archFrmt, not currentDirectoryPath, windowTitle, archiveFormat). All nouns should be abbrevaited to exactly 4 characters when possible and if makes sense (e.g. currDirctryPath not currDircPath). If a word is a noun and 5 characters long, the full word should be used.
  • All non-noun words should preferrably be abbreivated to exactly 4 characters when possible and if makes sense but must only be abbreivated to at least 3 characters.

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