From 1cd6f5ce154f8adf20c180277af338e9e8f4d433 Mon Sep 17 00:00:00 2001
From: Andrew Janke <andrew@apjanke.net>
Date: Fri, 29 May 2015 22:39:50 -0400
Subject: [PATCH] Minor markup formatting change

---
 Coding-style-guide.md | 57 +++++++++++++++++++++----------------------
 1 file changed, 28 insertions(+), 29 deletions(-)

diff --git a/Coding-style-guide.md b/Coding-style-guide.md
index 3f3b440..6ba7601 100644
--- a/Coding-style-guide.md
+++ b/Coding-style-guide.md
@@ -1,14 +1,14 @@
-##General Code Style##
+##  General Code Style  ##
 
 While you should follow the code style that's already there for files that you're modifying, the following are required for any new code.
 
-###Indentation###
+###  Indentation  ###
 
 Indent 2 spaces. No tabs.
 
 Use blank lines between blocks to improve readability. Indentation is two spaces. Whatever you do, don't use tabs. For existing files, stay faithful to the existing indentation.
 
-###Line Length and Long Strings###
+###  Line Length and Long Strings  ###
 
 Maximum line length is 80 characters.
 
@@ -29,7 +29,7 @@ long_string_2="I am an exceptionalllllllllllly
  looooooooooooooooooooooooooooooooooooooooong string."
 ```
 
-###Pipelines###
+###  Pipelines  ###
 
 Pipelines should be split one per line if they don't all fit on one line. 
 
@@ -63,7 +63,7 @@ $PWD
 
 TODO: Add a list of all environment variables you can use.
 
-###If / Loop###
+###  If / For / While  ###
 
 Put `; do` and `; then` on the same line as the `while`, `for` or `if`.
 
@@ -84,9 +84,9 @@ for dir in ${dirs_to_cleanup}; do
 done
 ```
 
-##Variables##
+##  Variables  ##
 
-###Naming Conventions###
+###  Naming Conventions  ###
 
 Meaningful self-documenting names should be used. If the variable name does not make it reasonably obvious as to the meaning of the variable, appropriate comments should be added.
 
@@ -109,7 +109,7 @@ local UPPERCASE=""
 UPPERCASE=""
 ```
 
-Variables name should not clobber command names, such as `dir` or `pwd`.
+Variable names should not clobber command names, such as `dir` or `pwd`.
 
 ```
 # Bad:
@@ -127,7 +127,7 @@ for zone in ${zones}; do
 done
 ```
 
-###Use local variables###
+###  Use local variables  ###
 
 Ensure that local variables are only seen inside a function and its children by using `local` or other `typeset` variants when declaring them. This avoids polluting the global name space and inadvertently setting or interacting with variables that may have significance outside the function.
 
@@ -150,9 +150,7 @@ echo "global_var = $global_var"  # global_var = 37
 # Good:
 function func_good() {
   local local_var=""
-
   local_var=37
-
   echo $local_var
 }
 
@@ -165,7 +163,7 @@ global_var=$(func_good)
 echo "global_var = $global_var" # move function result to global scope
 ```
 
-In the next example, lots of global variables are used over and over again, but the script "unfortunately" works anyway. The `parse_json()` function does not even return a value and the two functions shares their variables. You could also write all this without any function; this would have the same effect.
+In the next example, lots of global variables are used over and over again, but the script "unfortunately" works anyway. The `parse_json()` function does not even return a value and the two functions share their variables. You could also write all this without any function; this would have the same effect.
 
 Bad-Example: with global variables
 ```
@@ -259,7 +257,7 @@ parse_ubuntuusers_json
 echo "foobar: $counter - $i"
 ```
 
-###Constants and Environment Variable Names###
+###  Constants and Environment Variable Names  ###
 
 All caps, separated with underscores, declared at the top of the file.
 Constants and anything exported to the environment should be capitalized.
@@ -268,7 +266,7 @@ Constants and anything exported to the environment should be capitalized.
 # Constant
 readonly PATH_TO_FILES='/some/path'
 
-# Both constant and environment
+# Both constant and exported
 declare -xr ORACLE_SID='PROD'
 ```
 
@@ -284,7 +282,7 @@ done
 readonly VERBOSE
 ```
 
-###Read-only Variables###
+###  Read-only Variables  ###
 
 Use `readonly` or `declare -r` to ensure they're read-only.
 As globals are widely used in shell, it's important to catch errors when working with them. When you declare a variable that is meant to be read-only, make this explicit.
@@ -298,9 +296,9 @@ else
 fi
 ```
 
-##Functions##
+##  Functions  ##
 
-###Naming Conventions###
+###  Naming Conventions  ###
 
 Lower-case, with underscores to separate words. Parentheses are required after the function name. The `function` keyword is optional when `()` is present after the function name, but it aids readability and prevents [conflicts with alias declarations](http://zsh.sourceforge.net/Doc/Release/Shell-Grammar.html#Aliasing), so please use it!
 
@@ -333,7 +331,7 @@ function _helper_util() {
 }
 ```
 
-###Use return values###
+###  Use return values  ###
 
 After a script or function terminates, a `$?` from the command-line gives the exit status of the script, that is, the last command executed in the script, which is, by convention, 0 on success or an integer in the range 1 - 255 on error.
 
@@ -374,33 +372,34 @@ function my_good_func() {
 }
 ```
 
-###Check return values###
+###  Return values  ###
 
-Always check return values and give informative return values.
-
-For unpiped commands, use `$?` or check directly via an if statement to keep it simple.
+Always check return values and give informative error messages. For unpiped commands, use `$?` or check directly via an if statement to keep it simple. Use nonzero return values to indicate errors.
 
 ```
 # Bad:
 mv "${file_list}" "${dest_dir}/"
 
+# Good:
+mv "${file_list}" "${dest_dir}/" || exit 1
+
 # Good:
 if ! mv "${file_list}" "${dest_dir}/"; then
   echo "Unable to move ${file_list} to ${dest_dir}" >&2
-  exit "${E_BAD_MOVE}"
+  exit 1
 fi
 
 # Good: use "$?" to get the last return value
 mv "${file_list}" "${dest_dir}/"
 if [[ "$?" -ne 0 ]]; then
   echo "Unable to move ${file_list} to ${dest_dir}" >&2
-  exit "${E_BAD_MOVE}"
+  exit 1
 fi
 ```
 
-##Features and Bugs##
+##  Features and Bugs  ##
 
-###Command Substitution###
+###  Command Substitution  ###
 
 Use `$(command)` instead of backticks.
 
@@ -411,14 +410,14 @@ Nested backticks require escaping the inner ones with `\`. The `$(command)` form
 var="`command \`command1\``"
 
 # Good:
-var="$(command "$(command1)")"
+var="$(command \"$(command1)\")"
 ```
 
-###Eval###
+###  Eval  ###
 
 Eval is evil! Eval munges the input when used for assignment to variables and can set variables without making it possible to check what those variables were. Avoid `eval` if possible.
 
-##Sources##
+##  References  ##
 
 - [Shell Style Guide](https://google-styleguide.googlecode.com/svn/trunk/shell.xml)
 - [BASH Programming - Introduction HOW-TO](http://tldp.org/HOWTO/Bash-Prog-Intro-HOWTO.html)