My Code Formatting Guidelines
- 912 words
Software development is a varied field with varied opinions regarding varied ways of doing varied things. Everyone has their own opinionated takes on how code should be formatted. This leads to what can best be described as a conflated mess of conflicting thought. This is not something I, nor anyone else, ever want to deal with.
This is why we have code style guidelines. These guidelines outline how to format things so that everyone gets along and manslaughter is kept to a minimum. I myself have my own opinionated takes on how code should be formatted and find myself repeating the justification of my choices, so I’ve documented them here.
Worth noting is that I am a frontend developer, and that is reflected in my preferences and the technologies those preferences best apply to. I tend to build for the web using HTML, CSS, and JavaScript where possible, but often find myself working with more complex stacks incorporating languages such as PHP and TypeScript and a smattering of frameworks.
I personally enforce these settings using Prettier, which I feel does an excellent job. You can find my .prettierrc in my dotfile repo on GitHub. I’ve also noted the relevant Prettier options where applicable.
Use Tabs
Tabs should be used for indentation for several reasons. These include:
- Semantic indication of indentation
- Customisable display
- Improved accessibility
- Smaller file sizes
Prettier: useTabs: true
Always Add Semicolons
When writing JavaScript, every line that can end with a semicolon should end with a semicolon. JavaScript engines add them anyway, and it’s ideal to see exactly what code will be executed.
Prettier: semi: true
<span class="hljs-comment">// Bad</span>
<span class="hljs-keyword">function</span> name {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">"I truly do love JavaScript"</span>)
}
<span class="hljs-comment">// Good</span>
<span class="hljs-keyword">function</span> name {
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">"I truly do love JavaScript"</span>);
}
Use Double Quotes
Strings should use double quotes (""), not single quotes (''). This makes it easier to use single quotes (which are more common) within strings. This is merely a default, and there will be situations where using single quotes is preferable. For the most part, Prettier will handle these exceptions.
Prettier: singleQuote: true, jsxSingleQuote: false
<span class="hljs-comment">// Bad</span>
<span class="hljs-keyword">const</span> variable = <span class="hljs-string">'String Content'</span>;
<span class="hljs-comment">// Good</span>
<span class="hljs-keyword">const</span> variable = <span class="hljs-string">"String Content"</span>;
Quote Properties
Properties should all be quoted in the same way, rather than introducing unnecessary (and potentially confusing) variation within an object.
Prettier: quoteProps: "consistent"
<span class="hljs-comment">// Bad</span>
object = {
<span class="hljs-attr">property1</span>: <span class="hljs-string">"content"</span>,
<span class="hljs-string">"property2"</span>: <span class="hljs-string">"content"</span>
};
<span class="hljs-comment">// Good</span>
object = {
<span class="hljs-string">"property1"</span>: <span class="hljs-string">"content"</span>,
<span class="hljs-string">"property2"</span>: <span class="hljs-string">"content"</span>
};
Don’t Split Strings Across Multiple Lines
Strings should be contained within one line unless there is genuine reason not to do so. It makes things hard to search and is a general pain to deal with.
<span class="hljs-comment">// Bad</span>
<span class="hljs-keyword">const</span> variable = <span class="hljs-string">"This is awful. It may be easier for a human to read, but \
it leads to annoyance and makes it harder to search for things. It is an \
all around pain."</span>;
<span class="hljs-comment">// Good</span>
<span class="hljs-keyword">const</span> variable = <span class="hljs-string">"This is better. It may be a tad harder for a human to read, but resolves many annoyances and makes it easier to search for things. It is much cleaner as well."</span>;
Use Trailing Commas
Trailing commas help keep version history clean. Rather than a diff showing the implementation of a new line and a comma on the previous line, it will only display the actual change, a new line.
Prettier: trailingComma: "all"
<span class="hljs-comment">// Bad</span>
object = {
<span class="hljs-attr">property1</span>: <span class="hljs-string">"content"</span>,
<span class="hljs-string">"property2"</span>: <span class="hljs-string">"content"</span>
};
<span class="hljs-comment">// Good</span>
object = {
<span class="hljs-string">"property1"</span>: <span class="hljs-string">"content"</span>,
<span class="hljs-string">"property2"</span>: <span class="hljs-string">"content"</span>,
};
Space Brackets
Brackets should have spaces on either side to provide padding. This makes it easier to read and maintains consistency.
Prettier: bracketSpacing: true
<span class="hljs-comment">// Bad</span>
{<span class="hljs-attr">foo</span>: bar}
<span class="hljs-comment">// Good</span>
{ <span class="hljs-attr">foo</span>: bar }
Use Arrow Parentheses
Using arrow parentheses makes it easier to read and make changes.
Prettier: arrowParens: always
<span class="hljs-comment">// Bad</span>
x => x
<span class="hljs-comment">// Good</span>
(x) => x
Unwrap Prose
Prose formatting should be handled slightly differently to code. As such, each block of prose should be unwrapped into one line. This makes it easy for any editor to define how they want prose to display.
Prettier: proseWrap: preserve
HTML Whitespace Sensitive Formatting
Formatting HTML can be messy due to the way browsers parse whitespace. Prettier offers a good explanation of it, but the crux is that their CSS formatting option offers the best mix of human readability and preservation of whitespace.
Prettier: htmlWhitespaceSensitivity: css
Line Feed End of Line
Different operating systems handle line endings differently, and things get messy quick. Using line feed, which is common on Unix based systems, is a clean option that is also supported on Windows.
Prettier: endOfLine: lf
Format Embedded Languages
Code of one type used within a file of another should be formatted as you would code in it’s native filetype.
Prettier: embeddedLanguageFormatting: auto
Keep Multiple Attributes Per Line
Splitting an element’s attributes into multiple lines often makes it harder to quickly grasp structure and is an inefficient use of screen space.
Prettier: singleAttributePerLine: false
// Bad
<span class="hljs-tag"><<span class="hljs-name">div</span>
<span class="hljs-attr">class</span>=<span class="hljs-string">"name"</span>
<span class="hljs-attr">id</span>=<span class="hljs-string">"name"</span>
></span>
Content
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
// Good
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"name"</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"name"</span>></span>
Content
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
There you have my personal guidelines. I’m sure many people disagree (if only for my preference of tabs over spaces), and I’d love to hear your thoughts in the comments. All I ask is that you keep criticism constructive and remain respectful.
If you liked this post, then do consider sharing it. Also, if you’d like to support me in making more like it, consider sending me a tip. It’d mean a lot.