SeaPhor / SeaPhor-Scripts

my scripts

Objective- Effective Code Writing and Execution

For text version, see "Code-SOP..txt"

1. Synopsis

   1. The purpose of this document is to establish a "SOP" (Standard Operating Procedure) for creating and modifying code.
   2. The standards outlined here are to establish effective, efficient, common, readable, trackable, and accountable code-writing methodologies so that all code written by any member can be read, understood, and explained by any other member.
   3. The content here is not only to establish the SOP, but, also to create and/or follow known Best Practices, including but not limited to, PEP8 (see Resources).
   4. The reason for creating the SOP is to standardize all code written so that it can be efficiently read, understood, modified, and communicated without the need for either excessive time spent deciphering, or re-writing a new code ('re-inventing the wheel').

2. Scope

   1. This SOP should be implemented team-wide and was originally intended for BASH scripting, but, is hoped to be applicable to all code written.
   2. Must-Haves-
      1. Valid use-case and need
      2. Clear known objectives
      3. Outline- Including Objectives, Milestones, Test criteria, and completion state (Desired End Results). This should be documented in the header of the code itself.
      4. Stated possibility/s of risk/s and safegards for such.
      5. Structure, order, and comments, for easy reading, understanding, and standardization.
   3. Nice-To-Haves-
      1. Option/Parameter in calling the code/script, to print the objective outlined in the 'Must-Haves'.
      2. Some method of logging it's actions.
      3. "Script-Template" - As a team we should create, agree, and use a standardized script-template.

3. General Standards

   1. Use the "DRY" (Don't Repeat Yourself) principle, which states that you should NEVER repeat the same piece of code more than once in the same script/app.
   2. Make it OS/Release agnostic.
   3. Make it Portable- Environment, Network, and Infrastucture agnostic.
   4. Make it scaleable, allow for growth.
   5. Make it adaptable- Able to adjust with changed/better/new tools, methods, paths, etc. for anything that can/may change.
   6. Always use variables where common, multiple calls, or complex commands/strings are needed.
   7. For code that requires arguements/parameters passed on the command line-
      1. A help/usage statement option printing a menu.
         1. Standard- A conditional (Arithmatic) Expression check for the correct number of arguements passed and will print the usage message if '-ne'.
            1. Example- [[ ! $1 || $# -ne 1 ]] && { usage; echo "'$@' Not a valid option"; exit 1; }
            2. Use inside a function- EXAMPLE-

             cat <<EOT
         Usages and Oprions
         EOT
         }```
      

4. Process

   1. Evaluate the conditions
   2. Take action/s
   3. Carry out task/s
   4. Clean up and close

5. Standards

   1. Comments-
      1. Use comments for all sections, sub-sections, functions, and complex commands.
      2. Good comments explain 'why', not just how what is being done.
   2. Logging-
      1. Logging should include all stdin and stderr output.
      2. Logging for on-going and/or sceduled runs should be "self-rotating", based on size, using compression, and the archives rotated by date or number of archives,
      3. Date-Time-Stamps for logs should be structured for ease of debugging, eg. "2018_07_23-14:32:29"
   3. Indenting-
      1. It is recommended to use 4 SPACES for indentation, instead of TABS, however, whatever you do, BE CONSISTANT! Do NOT mix TABS and SPACES, use ONLY one of the following:
         1. 2 SPACES
         2. 4 SPACES
         3. 8 SPACES
         4. TABS (last choice)
   4. Variables-
      1. It is recommended to use only lowercase for variables, as all SYSTEM variables are in UPPERCASE, however, you can ONLY use letters, numbers, and underscores for declaring variables.
      2. Never combine UPPER and lower case, use one OR the other.
      3. As with "Indenting", whatever you do, BE CONSISTANT!
      4. There are different methods of calling variables, they each have their purpose, know (or learn) those differences and purposes. Example- [[ $HOME vs ${HOME} vs $(home) ]]
         1. See the various sub-sections under http://wiki.bash-hackers.org/syntax/expansion/
      5. Remember that variables contained within a funfion are limited to that function and are not available to the rest of the script, so declare global variables outside of functions where possible.
      6. Always declare global variables at the top-most part of the code.
      7. Always variable-ize the arguments passed on the cli, eg. "OPT_1=$1", "PARAM_1=$2", etc.
   5. IF statements-
      1. Use 'elif' statements instead of nested if-statements where possible.
      2. Use the Conditional structure where possible- Example

      •  [[ -e ${HOME}/.ssh ]] || { echo "No .ssh directory in ${HOME}"; exit 1; }
        

        1. Always use exit statements
   6. Loops (for, while, until)