Coding standards & scaffolding

My coding standards + snippets that I often reuse, like for checking stuff

Layout

Encoding

Use plain UTF-8 with Unix-style line ending
In coding, I frequently use special characters including →, ø, ő and €, so I can't ASCII like it's 1984, neither can I ignore the differences between UTF-8 and other character encoding standards

Line length

End lines at position 80:

As a first comment line, I usually have 80 # characters in a row
When later in a script, I would again use a 'full row' of # characters, but that line is intended, I would use less characters, so assure a line ending at 80

Tab

Use real tabs, rather than spaces
Length: 3

Note that this might slightly effect the effective line length (e.g., when someone opens a script in an environment with a longer tab length) - Let's not worry about that. Let's also not worry about the general discussion about using tabs vs. spaces.

Comment characters

Use # as default comment character or comment symbol, where possible. E.g., in SQL use # rather than -- or a custom symbol

When using languages that have a choice between 'single line comment characters' and 'opening & closing characters', use the former. E.g., commenting-out something in a PHP file:

//
// if ( true === $cache )
// {
//    set_transient( 'wc_layered_nav_counts_' . sanitize_title( $taxonomy ), $cached_counts, DAY_IN_SECONDS );
// }

Headings

Preferably, I stick to 2 levels of headings: 80x# & 40x#
Sometimes, this second level gets more than 40 characters, if I can't make a better shorter title
Sometimes I include a third level (no specific formatting, except for a : after the title).
I usually leave two empty lines before a heading
Occasionally I leave two empty lines between a heading + comments in the actual code.

Example:

#
# EanSku - Iteration 06 - Project delivery & project conclusion - Main script
################################################################################
#
# * Project EanSku - March 2020-April 2020
# * This is the main script - Everything this project does, is incorporated in 
#   this single script
#
#
################################################################################
# An annotated multiline query
################################################################################
#
# This is the only comment under this heading, hence no need to use bullets
#
# General stuff
########################################
#
select 
    wp_posts.id			as post_id,
    wp_posts.post_title		as post_title,
    wp_posts.post_name		as slug,
    wp_posts.post_content	as content,
    wp_posts.guid		as guid,
    wp_postmeta.meta_value	as sku,
    wp_postmeta_03.meta_value	as thumbnail_path,
    wp_postmeta_05.meta_value	as second_image_path,
    wp_postmeta_06.meta_value	as price
from 
    wp_posts


# First join to wp_postmeta to retrieve sku
###########################################
#
# Note that for this subheading, I used slightly more than 40 character
#
left join
    wp_postmeta
    on
    wp_posts.id = wp_postmeta.post_id


# Where clause
########################################
#
# * A first note
# * A second note
#
where 
    post_type="product"
    and
    post_status="publish"
    and
    wp_postmeta.meta_key="_sku"

Check if PWD is a WordPress site (Bash)

# Check if PWD is a WordPress site
########################################
#
if [ -e "wp-config.php" ]
then
   ...
else
   ...
fi

or like this, but keep the spaces around the { & } characters:

################################################################################
# Exit if PWD is not a WordPress site
################################################################################
#
[ ! -e "wp-config.php" ] && { echo "Not a WordPress site - Exiting"; exit }

Debugging (Bash)

Use variable debug as a Boolean to enable or disable debugging information being sent to the console
When variable debug is set outside of the script, you have to use source when invoking this script to preserve its value
Alternative: Declare debug inside the script
Alternative: Have debug as an optional argument when invoking this script (rarely implemented)

Examples

Basic example:

# debug="on"
# unset debug
#
[ "$debug" ] && echo "debug is set"
[ ! "$debug" ] && echo "debug is unset"

Example with multi-line output:

Use { & }
All commands need to end with a ; when these are on one line
{ and } need spaces around them:

[ ! -e "wp-config.php" ] && { echo "Not a WordPress site - Exiting"; exit; }

if [ "$debug" ]; then
   echo "Year: $year"
   echo "Month: $month"
fi

[ "$debug" ] && {
   echo ""
   echo "### assign_site_array"
}

or

[ "$debug" ] &&
{
   echo ""
   echo "### assign_site_array"
}

See also

Script wp_wc_fetch_revenue_figures.sh

Coding standards & scaffolding

Inhoud