My Code Formatting Guidelines

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

// Bad
function name {
	console.log("I truly do love JavaScript")
}

// Good
function name {
	console.log("I truly do love JavaScript");
}

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

// Bad
const variable = 'String Content';

// Good
const variable = "String Content";

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"

// Bad
object = {
	property1: "content",
	"property2": "content"
};

// Good
object = {
	"property1": "content",
	"property2": "content"
};

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.

// Bad
const variable = "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.";

// Good
const variable = "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.";

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"

// Bad
object = {
	property1: "content",
	"property2": "content"
};

// Good
object = {
	"property1": "content",
	"property2": "content",
};

Space Brackets

Brackets should have spaces on either side to provide padding. This makes it easier to read and maintains consistency.

Prettier: bracketSpacing: true

// Bad
{foo: bar}

// Good
{ foo: bar }

Use Arrow Parentheses

Using arrow parentheses makes it easier to read and make changes.

Prettier: arrowParens: always

// Bad
x => x

// Good
(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
<div
	 class="name"
	 id="name"
>
	Content
</div>

// Good
<div class="name" id="name">
	Content
</div>

---

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.