Why format matters
Writing is a means to convey information. Most languages, human or code, have a great deal of expressiveness built in by default. Format is expressive too. When format changes, it draws our mental attention to it, thus we should use it when we want to cause a shift in attention, like when a direct quote is italicized, or when we begin a new thought with a new paragraph. However, if we are reckless with our formatting, we can easily confuse readers. If we take the time to keep a consistent format and only change when we intend to, we are much more likely to convey our message to the reader.
Be consistent
It's impossible for the world, let alone a single person, to agree on a specific format. However, within a context, I think most would at least agree to be consistent. I would actually argue that most of us don't care about the specifics so long as it's easy to be consistent. The context is subjective, some examples might be a single file, a series of blog posts, or a particular project at work. The context is actually part of the specifics, so be consistent with it too!
Automate consistency
Manual enforcement is a disaster waiting to happen and it's a waste of time. There are lots of tools to help detect and many to help automatically fix inconsistencies. Even the most basic word processor can determine if you didn't put in a double space at the start of a sentence, and add it if desired. If paragraphs are indented, this can be automated too.
Computer languages
When starting a project, make sure you have an IDE or a tool to format your code. Here are some things to help evaluate a particular tool:
- Is it integrated with how you write your code?
- Can you easily execute (shortcut key) the cleanup on the current file(s) or a text selection?
- Can you version the configuration of specific rules within a context (line wrapping, spacing, indentation)?
- This allows others to automatically work in a new context, without needing to know the specifics.
- WebStorm is a fantastic example of an IDE where these settings can be shared with the team.
- The specifics of format are an artifact of the project, it evolves over time, so you should version that if you want to understand historical formats.
- Are all of the languages covered?
- Often, I see people clean up the primary language (c#) but not html and javascript.
Case Study: Blogging
As I was writing this, I realized how crappy it is to format this blog post. So I moved it to markdown, where I can focus on the content and not the presentation, where there are specific conventions already established to automatically format the content. For now I'm converting that to html to post to my blog, I would like to automate that step and wire it into a github repository so it's easy for me to blog about new things and not worry about the publishing step.
