refactor: use shellcheck item doc link instead of prolixity comments ✨

Author: oldratlee

bin/c

@@ -8,22 +8,6 @@
 #
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/shell.md#-c
 # @author Jerry Lee (oldratlee at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 set -eEuo pipefail
 
 readonly PROG=${0##*/}

bin/find-in-jars

@@ -13,22 +13,6 @@
 #
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/java.md#-find-in-jars
 # @author Jerry Lee (oldratlee at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 set -eEuo pipefail
 
 readonly PROG=${0##*/}
@@ -63,8 +47,6 @@ readonly LINE_CLEAR='\e[2K\r'
 
 # Getting console width using a bash script
 # https://unix.stackexchange.com/questions/299067
-#
-# NOTE: DO NOT declare columns var as readonly in ONE line!
 [ -t 2 ] && COLUMNS=$(stty size | awk '{print $2}')
 
 printResponsiveMessage() {

bin/show-busy-java-threads

@@ -8,22 +8,6 @@
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/java.md#-show-busy-java-threads
 # @author Jerry Lee (oldratlee at gmail dot com)
 # @author superhj1987 (superhj1987 at 126 dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 
 readonly PROG=${0##*/}
 readonly PROG_VERSION='2.x-dev'
@@ -38,7 +22,8 @@ readonly -a COMMAND_LINE=("${BASH_SOURCE[0]}" "$@")
 #   See https://www.lifewire.com/current-linux-user-whoami-command-3867579
 # Because if run command by `sudo -u`, env var $USER is not rewritten/correct, just inherited from outside!
 #
-# NOTE: DO NOT declare var USER as readonly in ONE line!
+# DO NOT declare and assign var USER(as readonly) in ONE line!
+#   more info see https://github.com/koalaman/shellcheck/wiki/SC2155
 USER=$(whoami)
 readonly USER
 
@@ -220,7 +205,7 @@ uname | grep '^Linux' -q || die "$PROG only support Linux, not support $(uname)
 # parse options
 ################################################################################
 
-# DO NOT declare var ARGS as readonly in ONE line!
+# DO NOT declare and assign var ARGS(as readonly) in ONE line!
 ARGS=$(
   getopt -n "$PROG" -a -o c:p:a:s:S:i:Pd:FmlhV \
     -l count:,pid:,append-file:,jstack-path:,store-dir:,cpu-sample-interval:,use-ps,top-delay:,force,mix-native-frames,lock-info,help,version \
@@ -371,7 +356,7 @@ readonly jstack_path
 # biz logic
 ################################################################################
 
-# NOTE: DO NOT declare var run_timestamp as readonly in ONE line!
+# DO NOT declare and assign var run_timestamp(as readonly) in ONE line!
 run_timestamp=$(date "+%Y-%m-%d_%H:%M:%S.%N")
 readonly run_timestamp
 readonly uuid="${PROG}_${run_timestamp}_${$}_${RANDOM}"
@@ -433,6 +418,7 @@ findBusyJavaThreadsByPs() {
   # shellcheck disable=SC2206
   local -a ps_cmd_line=(ps $ps_process_select_options -wwLo 'pid,lwp,pcpu,user' --no-headers)
   # DO NOT combine var ps_out declaration and assignment in ONE line!
+  #   more info see https://github.com/koalaman/shellcheck/wiki/SC2155
   local ps_out
   ps_out=$("${ps_cmd_line[@]}" | sort -k3,3nr)
   [ -n "$ps_out" ] || __die_when_no_java_process_found
@@ -473,7 +459,7 @@ __top_threadId_cpu() {
   # 4. top v3.3, there is 1 black line between 2 update;
   #    but top v3.2, there is 2 blank lines between 2 update!
   local -a top_cmd_line=(top -H -b -d "$cpu_sample_interval" -n 2 -p "$java_pid_list")
-  # DO NOT combine var ps_out declaration and assignment in ONE line!
+  # DO NOT combine var top_out declaration and assignment in ONE line!
   local top_out
   top_out=$(HOME=$tmp_store_dir "${top_cmd_line[@]}")
   if [ -n "$store_dir" ]; then

bin/uq

@@ -10,22 +10,6 @@
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/shell.md#-uq
 # @author Zava Xu (zava.kid at gmail dot com)
 # @author Jerry Lee (oldratlee at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 set -eEuo pipefail
 
 readonly PROG=${0##*/}
@@ -217,11 +201,12 @@ done
 [[ $uq_opt_all_repeated == 1 && $uq_opt_repeated_method == none && ($uq_opt_count == 0 && $uq_opt_only_repeated == 0) ]] &&
   yellowPrint "[$PROG] WARN: -D/--all-repeated=none option without -c/-d option, just cat input simply!" >&2
 
-# NOTE: DO NOT declare var uq_max_input_size as readonly in ONE line!
+# DO NOT declare and assign var uq_max_input_size(as readonly) in ONE line!
+#   more info see https://github.com/koalaman/shellcheck/wiki/SC2155
 uq_max_input_size=$(convertHumanReadableSizeToSize "$uq_max_input_human_readable_size") ||
   usage 2 "[$PROG] ERROR: illegal value of option -XM/--max-input: $uq_max_input_human_readable_size"
 
-readonly argc=${#argv[@]} argv
+readonly argc=${#argv[@]} argv uq_max_input_size
 
 if ((argc == 0)); then
   input_files=()

bin/xpl

@@ -7,22 +7,6 @@
 #
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/shell.md#-xpl-and-xpf
 # @author Jerry Lee (oldratlee at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 set -eEuo pipefail
 
 readonly PROG=${0##*/}

legacy-bin/cp-svn-url

@@ -8,22 +8,6 @@
 #
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/vcs.md#-cp-svn-url
 # @author ivanzhangwb (ivanzhangwb at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 
 readonly PROG=${0##*/}
 readonly PROG_VERSION='2.x-dev'
@@ -74,7 +58,8 @@ done
 
 readonly dir="${1:-.}"
 
-# NOTE: DO NOT declare var url as readonly in ONE line!
+# DO NOT declare and assign var url(as readonly) in ONE line!
+#   more info see https://github.com/koalaman/shellcheck/wiki/SC2155
 url="$(svn info "${dir}" | awk '/^URL: /{print $2}')"
 if [ -z "${url}" ]; then
   echo "Fail to get svn url!" >&2

lib/console-text-color-themes.sh

@@ -4,22 +4,6 @@
 #
 # @online-doc https://github.com/oldratlee/useful-scripts/blob/dev-2.x/docs/shell.md#-console-text-color-themessh
 # @author Jerry Lee (oldratlee at gmail dot com)
-#
-# NOTE about Bash Traps and Pitfalls:
-#
-# 1. DO NOT combine var declaration and assignment which value supplied by subshell in ONE line!
-#    for example: readonly var1=$(echo value1)
-#                 local var2=$(echo value1)
-#
-#    Because the combination make exit code of assignment to be always 0,
-#      aka. the exit code of command in subshell is discarded.
-#      tested on bash 3.2.57/4.2.46
-#
-#    solution is separation of var declaration and assignment:
-#           var1=$(echo value1)
-#           readonly var1
-#           local var2
-#           var2=$(echo value1)
 
 colorEcho() {
   local combination=$1