DEV Community: Moniet Sawhney

JS Clean Code — Learning on the job

Moniet Sawhney — Sun, 11 Apr 2021 14:09:05 +0000

In this post, I've compiled a few tidbits that have helped make my React / JavaScript projects that tiny bit more readable.

Looking forward to discuss, iterate, and improve !

prerequisites

optional chaining
short circuiting
higher order functions
es6
react.js
styled-components || emotion

short circuiting to keep things clean

// assume 'data' here is an array of objects

const mapValues = 
  data
    ? data.map(({ value }) => value) 
    : []

// --------------
// cleaning up ✨
// --------------

const mapValuesCleanedUp = 
  (data || []).map(({ value }) => value)

The advantage with this pattern is that it can avoid nesting the ternary operators which can be hard to read.

If we need to pass another set of data we can do so with ease. For example : (data || otherData || []).map(...). This same change with the ternary operator would result in nesting. For example :

const nestedTernary =
  data 
    ? data.map(...)
    : otherData 
      ? otherData.map(...)
      : []

Note : Short circuiting can be a cause for some pretty counterintuitive bugs. I would recommend going through this article to learn more about it (and a little something something about ES2020).

arrays to keep things DRY

const isValidZipCode = 
  (value) => value.length === 5 || value.length === 10

// --------------
// cleaning up ✨
// --------------

const isValidZipCodeCleanedUp = 
  (value) => [5,10].includes(value.length)

With this trick we don't have to repeat the value.length bit, and if the requirements grow beyond just 5 and 10 the array can be extended like so: [5,10,6].includes(value.length).

the good ol' IIFE for consistency

// formatting variable data
// in this ex : the 'data' object
// contains one property 'cities'
// and two properties for getting states, i.e.
// 'statesData' and 'allStates'

const formatLocaleData = (data = {}) => {
    const { statesData, allStates, cities = [] } = data

    const getFormattedStates = () => { // <--
        if (statesData) return statesData.map(mapOneWay)
        if (allStates) return allStates.map(mapAnotherWay)
        return []
    }

    return {
        cities, // <-- 
        states: getFormattedStates(), // <-- 
    }
}

// --------------
// cleaning up ✨
// --------------

const formatLocaleDataCleanedUp = (data = {}) => {
    const { statesData, allStates, cities = [] } = data

    const states = (() => { // <--
        if (statesData) return statesData.map(mapOneWay)
        if (allStates) return allStates.map(mapAnotherWay)
        return []
    })()

    return {
        cities,  // <-- 
        states,  // <--
    }
}

The entire idea for me in this example was to keep the return object consistent by getting rid of the getFormattedStates().

The allStates and statesData are mapped separately (for the same result) so that my react component can consume it.

After cleaning it up, the IIFE maps data and assigns it to the states variable in one go.

destructuring props for easier fallbacks

const MyComponent = ({ data }) => {
    const fallback = "loading..."

    return (
        <div>
            <h1>{data?.header || fallback}</h1>
            <p>{data?.summary || fallback}</p>
        </div>
    )
}

// --------------
// cleaning up ✨
// --------------

const MyComponentCleanedUp = ({ data = {} }) => {
    const fallback = "loading..."
    const { header = fallback, summary = fallback } = data

    return (
        <div>
            <h1>{header}</h1>
            <p>{summary}</p>
        </div>
    )
}

I was often using the short circuiting pattern like : {data.header || "fallback"} in my react components.

However, if you need to access numerous properties it really helps to have all the fallback values in one place rather than multiple this || that conditions in different places.

better theming in styled-components

import { themeGet } from '@styled-system/theme-get'
import styled from 'styled-components'

const Card = styled.div`
    ...

    border-width: ${({ theme }) => 
        theme.borderWidths.small 
            ? theme.borderWidths.small 
            : "2px"
    };

    ...
`

// --------------
// cleaning up ✨
// --------------

const CardCleanedUp = styled.div`
    ...

    border-width: ${themeGet('borderWidths.small', '2px')}

    ...
`

As you can see, the themeGet utility makes things super concise. It was developed as part of the styled-system library, but it can be installed and used individually.

It's super simple to use. The themeGet function's first argument is the property you want to access and the second arguement is the fallaback .

This is by no means only limited to styled-components you can also use it with other CSS-in-JS solutions like emotion.

sane styled components with the CSS prop


const DivRelative = styled.div`
    position: relative;
`

const MyComponent = () => (
    <DivRelative>
        "..."
    </DivRelative>
)

// -------------
// cleaning up ✨
// -------------

const MyComponentCleanedUp = () => ( 
    <div css="position: relative;">
     "..."
  </div>
)

On large projects, I found that I often had to create styled components with super random names that had only one line of css (like <DivRelative />) above.

I'd waste precious time thinking of a component name that made an inkling of sense.

The css prop was the definitive answer to this problem !

Note : To use the css prop you need include the babel-styled-components plugin in your babel configuration.

conclusion

Above all else, I think one of the most important things is to keep things as consistent as possible. It's easy to predict how things work when there is consistency (especially in monolithic setups).

When adopting new patterns it's imperative that everyone on your team is onboard with the idea and that it actually contributes improved readability. That goes for adopting the above snippets too.

I've often found myself reaching for patterns because it made me feel like a boss but didn't really contribute anything substantial to readability. I once named a component <LobotomizedOwl /> for example 🤦‍♂️. But I did change it to better name like <MarginProvider />. Learn from my mistakes and don't do this !

Which brings me to another topic, naming things.

Naming things is also important in projects. It can cause a lot of confusion when things are not named properly.

For example, it's okay to have longer variable / function names if it clarifies the context for future devs. In this light, something like : getHumanReadableDatesForSelectElement() is totally fine. Maybe in this hypothetical project there's 10 different requirements for dates. In this case descriptive variable names could reduce the WTFs per minute.

And of course, it's worth mentioning that comments can and should be used to clarify things. Sometimes code is forced to be complex and in those cases comments can help everyone. Especially junior devs.

Here's a great talk by Sara Drasner on 'The Art of Commenting'.

As much as I'm about 'aesthetically pleasing' code, which longer variable names might not be. I'm also inspired by a common saying in the design community :

"Form follows function"

Kurzgesagt Earth - A CSS Recreation

Moniet Sawhney — Wed, 12 Jun 2019 13:40:02 +0000

The idea behind this project was to recreate an illustration found in YouTube channel Kurzgesagt's videos (as seen in the image above); limiting my self to using HTML and CSS.

Through creating this illustration, my aim was to learn and utilize various techniques of layouts and responsive design. In addition, I wanted to practice writing maintainable sass code using the BEM methodology.

Lastly, by documenting the process of creating the illustration I hope to share my knowledge on layouts and expose a few quirks of CSS.

First Steps

Using the drop tool

I used the colour picker tool in Firefox to grab the colour palette from Kurzgesagt's video. In Firefox, the colour tool automatically copies the HEX value to the clipboard. In this manner, I was able to create a palette with variable in SCSS like so:

// Palette
$earth-blue: #208bd2;
$trees: #45cb69;
$earth-outline-blue: #0a1436;
$earth-aura: #10329b;
$clouds: #ffffff;
$bg: #03081b;

Looking at the BEM methodology, I find the it is important to have descriptive names not only for html tags, but also for variables, mixins, and extends.

In this manner, it will be easier to recall the code by memory which ultimately allows for quicker changes.

Initial Structure

When starting, I find it important to define the structure starting with the 'blocks' or the main chuncks of html that define the blueprint for the layout. Looking at the illustration, I defined a base structure based on the following blocks: earth, clouds, trees, and earth's aura.

// base structure
<div class="wrapper">

    <div class="earth">
      <div class="earth_shadow_container">
        <div class="earth_shadow"></div>
      </div>

      <div class="clouds">
        <div class="lines_1"></div>
        <div class="lines_2"></div>
      </div>

      <div class="trees">
        <div class="line_1"></div>
        <div class="line_2"></div>
      </div>
    </div>

    <div class="earth_aura">
    </div>

    <div class="bg">
    </div>

  </div>

Above, I use descriptive names for blocks. This is in accordance with BEM's guide for naming tags which states that you should describe the block's purpose, and not its state.

Although it may be slightly abstracted for an illustration; I strongly feel it is still good practice to pay attention to small things like naming conventions, as they make the code a lot more readable.

Moreover, the wrapper - which will contain all the elements - has the following CSS code to render the art in full-screen:

.wrapper {
  display: block;
  position: relative;
  margin: 0 auto;
  width: 100vw;
  height: 100vh;
}

Apart from making it full-screen, the above code will allow for elements within to be easily centered relative to the users 'viewport', which is their device's screen. This is accomplished by using the vw and vh relative units in CSS.

Making Earth

Next, I began putting together the 'base' for the entire illustration which was the earth; its background, border, width, and height.

.earth {
  position: relative;
  width: 30vw;
  height: 30vw;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background: $earth-blue;
  border: solid 1vw $earth-outline-blue;
  border-radius: 50%;
  z-index: 0;
  overflow: hidden;
}

Here, again, I use the vw unit to size the earth, this is because it will re-size based on the viewport's dimensions, so anyone can see it on their device.

Most notably, the following code centers the earth, right in the middle of the screen (both vertically and horizontally):

top: 50%;
left: 50%;
transform: translate(-50%, -50%);
background: $earth-blue;

To keep my code DRY, I took the above snippet and created an instance of @extends that would allow me to re-use it in other places.

The extend snippet looks like this:

%centerElement {
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}

Now we have an earth that looks like this:

The Aura

Next, I focused on creating the earth aura. My idea behind this was that I could create the basic background with the 'earth-aura' block, and build the other three aura rings with the :before, and :after pseudo-elements.

One important takeaway from the project was how useful the z-index attribute is. The z-index attribute will allow you to defined the 'layers' of the elements. In a nutshell (pun intended), allowing you to decide which element is at the top, bottom, and the middle.

Completing the aura, the earth now looks like this:

The Dark Side of the Earth

This was a tricky bit of code to write, and there are several ways to do it, such as the clip-path. However, I stuck with using a simple div and changing it's overflow to none. The code can be a bit confusing, but it's definitely a useful technique.

The CSS for the earth shadow:

.earth_shadow_container {
  position: absolute;
  left: 50%;
  width: 100%;
  height: 100%;
  overflow: hidden;
}
.earth_shadow {
  position: absolute;
  left: -50%;
  width: 100%;
  height: 100%;
  background: rgba(0,0,0,0.2);
  border-radius: 50%;
  z-index: 1000;
}

Notice the z-index is large, as it will allow the clouds and trees to be under it.

It looks like this:

The Trees

Similar to the earth aura, I used a combination of elements, their pseudo elements, and box-shadow, to create trees.

First, I centered the 'trees' container within the earth block. Following this I coded the trees like so:

.line_1 {
    position: absolute;
    top: 75%;
    left: 20%;
    width: 12vw;
    height: 4vw;
    background: $trees;
    border-radius: 50px;

    &:after {
      content: '';
      position: absolute;
      display: block;
      top: -150%;
      left: 70%;
      width: 8vw;
      height: 3vw;
      background: $trees;
      border-radius: 50px;
    }

    &:before {
      content: '';
      position: absolute;
      display: block;
      top: -200%;
      left: -50%;
      width: 5vw;
      height: 2vw;
      background: $trees;
      border-radius: 50px;
    }

  }

The same process was done for the clouds. Lastly, I touched up the illustration with CSS animations, and added a descriptive header.