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
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
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.
this is purely superficial.
* `&&` is a short-circuiting operator that only evaluates
its right-hand side when `$?` is `0`. `&&` is preferred
@ -82,17 +81,22 @@ RUN : \
non-zero exit code to indicate that an error occurred,
whereas `;` will continue executing code,
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`.
**important:** `||` has a lower precedence than `&&`!
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 ;} \`
* leftmost `&&`s and `||`s are always centered within their 4-space indent.
* avoid using pipes (`|`) when possible, because only the
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
without any braces or other commands.
@ -101,22 +105,22 @@ RUN : \
similar to how `RUN :` begins a shell command.
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.
thankfully, the space between `;` and `}` is optional.
* a final `;` is used to finish off the line-continutation.
this means that every line before it can end with a `\`,
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.
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.