Best practices for writing CSS and JavaScript with a team

Yesterday, I wrote about the importance of understanding the medium that we work in. Today, I wanted to share my best practices for writing code with a team.

Here’s the short list:

1. Have and enforce code style guides.
2. Document your code.
3. Use lots of inline comments.
4. Automate testing.
5. Build a culture of mentoring.

Let’s dig into each of these just a little bit more.

Code Style Guides

A code style guide defines the coding norms for your code base.

Do you use let or const as the default for assigning variables? Arrow functions or function declarations? What naming convention do you use for your CSS classes and JavaScript functions?

Here’s an example…

Brackets should always be used for coding blocks.

// ❌ Don't do this
if (isLoggedIn)
	showContent();

// ✅ Do this
if (isLoggedIn) {
	showContent();
}

If you need a starting point, here are the ones Google uses for HTML/CSS and JavaScript.

Document your code

One of the most common challenges I see at a lot of organizations, both big and small, is that they “move fast” and never slow down to document what they’ve done and how it works.

Have a question about what a piece of code does or why it’s there? “Go talk to Scott. He’s been around longest and knows all of that.”

That works ok… until Scott gets sick, fired, or quits. Then no one knows how anything works anymore.

I’ve seen this play out so many times in my career.

Open a .txt or .md file and write down…

1. How to install or setup the code.
2. What each file, section, or module does.
3. How to modify and update things.

Generally speaking, more detail is better, but even starting here is better than 95 percent of what I see “in the wild.”

Use lots of inline comments

A few years ago, I shared Dr. Kate Compton’s tip for writing better comments

Programming pro tip: In your comments, write what you did and why, record your level of petulance (REALLY) and the StackOverflow link that made you realize something

Here’s an example using the JSDoc format.

/**
 * Copy into the local scope
 * NOTE: this has issues with scope for eval'ing list comprehensions, which sucks
 * {@link https://stackoverflow.com/questions/45194934/eval-fails-in-list-comprehension}
 */

You ever run into a piece of code that seems like it doesn’t need to be there? Comments like this help you understand what the code does and why it’s included.

They’re for others, and they’re also for future you, who will absolutely forget things like this over time.

While JavaScript has a well-used convention with JSDoc, CSS does not. I tend to use a JSDoc-like style in my CSS, and encourage others to do the same.

/**
 * @section CSS Reset
 * Adapted from Andy Bell's modern CSS reset
 * @link https://hankchizljaw.com/wrote/a-modern-css-reset/
 */

/**
 * Remove the tap delay in webkit
 * @link https://medium.com/@adactio/delay-a9df9edceef3#.7dmbl3xow
 */

That last comment is a good example, actually.

The tap delay was removed from webkit on mobile-optimized sites ages ago, and so that code can probably be removed. Without the comment, you’d be stuck wondering why it’s there, or go on a scavenger hunt to figure out what it does.

Automate testing

If you’re worried about junior devs breaking things, review their code and automate testing.

(Senior devs break code all the time, too!)

While unit testing gets a lot of hype, end-to-end testing let’s you test that all of the pieces in your app actually work the way they’re supposed to. And visual regression testing can catch unintended style changes before they ship.

Writing tests definitely involves a bit of work, but can add an extra layer of security and can be automatically run whenever you try to merge code.

Build a culture of mentoring

The most effective teams elevate each other.

They review each others code. They explain issues they find. They teach each other things they don’t know.

This isn’t just a junior-to-senior thing. A lot of more senior developers have patterns they’ve developed over the years that are replaced by simpler, more modern techniques they never learned.

Often, more junior developers learned the new approaches, and can share those with their more seasoned peers.

Tech is great, but it’s not a catchall

I obviously love technology. I work in a tech field.

But it’s not the catchall for every problem. If your team is struggling to name things or write good CSS or organize their code… address those things! Don’t just cover them up with fancy tooling.

Address the root of the problem and you’ll be a much better team for it.