User:Franklin Yu/Coding styles

"It's easier to ask forgiveness than it is to get permission."

- Grace Hopper

Unspecified details default to Google style; fall back to GitHub style.


 * Use Shebang for executable scripts; remove file-type suffix.
 * Many languages provide a special pointer called  or , including C++, C#, Java, and Swift/Objective-C. Although not explicitly mentioned in most style guides, it is typically omitted when the compiler understands it correctly (basically everywhere except in constructors). However, it’s usually useful to recognize instance variables without the help of an IDE, so several style guides developed a convention to use some prefix or suffix to distinguish (most commonly an underscore). This sounds Hungarian notation, repeating what   was for. Decision:
 * For languages with a clear owner (such as Apple for Objective-C, and Microsoft for C#), if the owner decides to use a prefix or suffix, follow the owner. This means that the pointer is redundant, and should be omitted. Note that for C#, .NET foundation is considered de facto owner in addition to Microsoft.
 * For languages without a clear owner (notably C++), or if the owner doesn’t require such a prefix or suffix (notably Java), use the pointer instead of a prefix or suffix.
 * For C/C++, shell scripts (POSIX, Bash, Zsh), Swift, CSS, and HTML: indent with tabs and align with spaces.
 * For C/C++, the main function return with macros or.
 * For structs and unions in C, use the style  instead of   as , for same reason as in the Linux kernel style. Note that this rule doesn’t apply to C++.
 * For Python, fall back to PEP 8.
 * For systemd unit files, keep a space around the equal sign for readability.
 * When creating command-line flags, use kebab-case like  and  . If kebab-case is forbidden, prefer   over   (a.k.a. lower camel-case).

Git commit message
Follow the Vim specification: first line is the summary, no longer than 50 characters; leave the second line empty; limit to 72 characters for other lines (except for long URL). More rules:
 * Use “Sentence case” for the summary, as if writing a sentence, but omit the period mark. Use an imperative sentence, such as “Delete foo”, instead of “Deleting foo” or “Deletes foo”.
 * If the change is trivial (re-format, fix typo, etc.), add a  trailer to the message. I used to prefix   to the summary line, inspired by how MediaWiki presents meta:Help:Minor edit; however, the trailer way makes use of existing tools, allows extensibility, and saves four (out of only 50!) characters for the summary line.
 * Use some Markdown in the body, but make sure it reads good as plain text.

Java

 * Google prefers no delimiter for package names, but in reality this makes words hard-to-read like . Some projects work around this by creating redundant (and non-semantic) package levels, like   with no other packages in the prefix  . Since underscore in package names (like   has negligible compatibility issue, I prefer underscore.
 * Google prefers to group all non-static imports together. When there are more than 10 non-static imports, I find it cleaner to separate the ones for JDK from the ones for other dependencies (like Spring Framework).

JavaScript/TypeScript

 * For plain JavaScript that are highly unlikely to go into Google, use StandardJS instead of Google style. Use Google style for all TypeScript.
 * Avoid built-in,   and.

Makefile

 * implicit rules
 * auto-dependency generation
 * Avoid  suppressing recipe echoing. Echoing provides valuable debugging information, such as variable expansion. It should typically be up to the user to decide whether to suppress the echoing (with  / ). A common pattern is to replace all echoing within a target with a manual  ; this pattern can be better achieved with.

Ruby

 * Use the Robocop style for Ruby and Rails; fall back to Google, then GitHub style.
 * RSpec guides
 * Fix major version of gems in  (with  ).

shell scripts

 * For statements below, “all shells” means Bash, Zsh, Dash, and BusyBox; they cover most cases, so should be good enough.
 * Omit unnecessary braces for parameter expansion, such as  and , instead of   and.
 * For builtin, use the   version with long names instead of short names like  . Recommended options are   and  . Non-POSIX  is also recommended when in Bash/Zsh.
 * Use kebab-case for aliases. This is not POSIX, but it’s supported in all shells. Kebab-cases are more readable and easier to type (one less Shift).
 * Use kebab-case for functions in Bash/Zsh. They are not supported in Dash or BusyBox.
 * When a command provides multiple versions of the same option (such as /  in GNU Diff), avoid the single-letter one. Optimize for readers, instead of authors; short form is good for interactive sessions.
 * Prefer  over , since the former makes the binding relationship more obvious (the latter might be a Boolean flag and a positional argument). For long flags, prefer double dash like   over single dash like  ; reserve single dash for short forms (when long form isn’t available, or for interactive usage).
 * Declare variables as local when in functions. The  builtin is non-POSIX, but it is supported in all shells.
 * Keep a single space before, but not after, the I/O redirection operator (i.e.  and  ). Rationale: the operator binds closer to the word after it (i.e. the file path); compare   and.
 * For Zsh, do not quote a single variable like  into , since Zsh doesn’t expand them like Bash does.

wrapping long commands
The Google style guide recommend wrapping long commands with backslashes (escaping character ), like

I prefer avoiding backslashes as much as possible, making use of the fact that a pipe won’t end a command:

Explanation of the example above:  to   are on the same line because they fit within the width limit. The first few words of  actually fits in the   line, but not the entire command, so it is put in a new line to avoid the backslash. The backslash in  cannot be avoided, so we use an additional level of indentation to emphasize that.

Note that logical operators  and   (for “and-or list” ) also won’t end a command, so the same trick applies. Common example:

use shell features instead of helper commands
Avoid UUoC. When in Bash/Zsh, also avoid useless  like:

Use here strings instead, like: