notwa/stargazing
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refine code style section

Browse Source
This commit is contained in:
Connor Olding 2022-09-23 12:22:51 -07:00
parent c490e26fb9
commit a7da48e7ec
1 changed files with 13 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -64,7 +64,7 @@ RUN : \
; ;
``` ```
*gratuitous explanation:* #### gratuitous explanation
* 4-space indentation is a must, since at least three characters * 4-space indentation is a must, since at least three characters
are needed to contain the operators on the left of each line. are needed to contain the operators on the left of each line.
@ -72,9 +72,8 @@ RUN : \
* `:` is akin to the `true` command; it's used as a no-op * `:` is akin to the `true` command; it's used as a no-op
that only sets the most recent exit code (`$?`) to `0`. that only sets the most recent exit code (`$?`) to `0`.
* `\` continues the code to the next line; * `\` continues the shell command to the next line;
the proceeding newline is removed and ignored. the proceeding newline is removed and ignored.
this is purely superficial.
* `&&` is a short-circuiting operator that only evaluates * `&&` is a short-circuiting operator that only evaluates
its right-hand side when `$?` is `0`. `&&` is preferred its right-hand side when `$?` is `0`. `&&` is preferred
@ -82,17 +81,22 @@ RUN : \
non-zero exit code to indicate that an error occurred, non-zero exit code to indicate that an error occurred,
whereas `;` will continue executing code, whereas `;` will continue executing code,
even in the presence of an error. even in the presence of an error.
**note:** the `diff` command breaks the convention
and uses both `0` and `1` as normal exit codes.
* `||` is like `&&` but only executes when `$?` is *not* `0`. * `||` is like `&&` but only executes when `$?` is *not* `0`.
**important:** `||` has a lower precedence than `&&`! **important:** `||` has a lower precedence than `&&`!
make sure to wrap your `||`s in braces unless you want to make sure to wrap your `||`s in braces unless you want to
capture *everything* before it. for instance: capture *everything* before it. for example, an excerpt
of a shell script might look like this:
` && { test -e myfile || touch myfile ;} \` ` && { test -e myfile || touch myfile ;} \`
* leftmost `&&`s and `||`s are always centered within their 4-space indent. * leftmost `&&`s and `||`s are always centered within their 4-space indent.
* avoid using pipes (`|`) when possible, because only the * avoid using pipes (`|`) when possible, because only the
exit code of the final command in any pipe is respected. exit code of the final command in any pipe is respected.
instead, write intermediate data to `/tmp` when possible.
remember to mount `/tmp` as a `tmpfs` at the start of the `RUN` command!
* functions are declared (`()`) on their own line * functions are declared (`()`) on their own line
without any braces or other commands. without any braces or other commands.
@ -101,22 +105,22 @@ RUN : \
similar to how `RUN :` begins a shell command. similar to how `RUN :` begins a shell command.
sadly, the space between the brace and the colon is not optional. sadly, the space between the brace and the colon is not optional.
* ';}` is used to finish a multi-line block. * `;}` is used to finish a multi-line block.
this is aligned with the preceeding `&&` and `||` operators. this is aligned with the preceeding `&&` and `||` operators.
thankfully, the space between `;` and `}` is optional. thankfully, the space between `;` and `}` is optional.
* a final `;` is used to finish off the line-continutation. * a final `;` is used to finish off the line-continutation.
this means that every line before it can end with a `\`, this means that every line before it can end with a `\`,
which simplifies editing. when podman gives you strange errors, which simplifies editing. when podman gives you strange errors,
double-check that you aren't forgetting the final semicolon. double-check that you aren't forgetting a `\` or the final semicolon.
* redirections are usually specified *before* a final list of arguments. * redirections are usually specified *before* a final list of arguments.
this makes skimming code easier when arguments extend across many lines. this makes skimming code easier when arguments extend across many lines.
* **TODO:** explain `if cmd ␤ ;then : ␤ ;fi`. * **TODO:** explain `if cmd \␤ ;then : \␤ && cmd \␤ ;fi`.
* **TODO:** explain `for cmd ␤ ;do : ␤ ;done`. * **TODO:** explain `for cmd \␤ ;do : \␤ && cmd \␤ ;done`.
* **TODO:** explain `while cmd ␤ ;do : ␤ ;done`. * **TODO:** explain `while cmd \␤ ;do : \␤ && cmd \␤ ;done`.
* **TODO:** explain `test`s. * **TODO:** explain `test`s.