Forem: Jaff Parker

How do you convince clients to go with Gatsby instead of Wordpress?

Jaff Parker — Sun, 07 Jul 2019 20:31:26 +0000

A question for freelancers out there: I have a client who is very used to her Wordpress installation, but the exact same thing could be done with Gatsby + Netlify CMS. I can't seem to convince her to switch and I can't stand how complicated Wordpress is.

Have you faced a situation like this where you ended up convincing your client to switch? How did you do it? Or did you just silently swap hoping they wouldn't notice?

How to Produce Readable Code

Jaff Parker — Mon, 17 Jun 2019 19:04:34 +0000

This is the first installment in a series of articles of indefinite length.

Throughout the years of working in various teams and building one, I have grown to appreciate code quality more than the actual tooling that the team uses. It doesn't matter what language you write in or what framework you use, anyone can get on board, if your code matches certain quality standards.

I want to share my experience to help startups out there expand their hiring pool by making their codebase easy to read and comprehend.

What's readable?

What on Earth am I talking about? Is it a sufficient amount of // comments? Maybe it's an abundance of s p a c e s? Indentation? Documentation?..

All of those are important, if done right. If you have ambiguous code, add clear comments to it. You do need to make sure your indentation and spaces are consistent. And you sure should write docs from the beginning (that might just be an article in this series).

In this post though I will talk about English. That is, the language. Spanish or Chinese can work too, but they'll highly limit your hiring pool, so English it is.

Why language in coding is important

In most languages humans use nouns to identify objects and verbs to express actions on those objects. That's how we read English.

If we start substituting verbs and nouns, it becomes literally impossible to understand the meaning of words. Here's this sentence with verbs and nouns swapped:

If we beginning substitution verbs and nouns, it start literally impossible to understanding the mean of speak.

The hell is this, right? I wanted to carve my eyes out writing that.

So why would we write code like this:

function user() {
  return {
    id: '1',
    name: 'Mr. Poopy Butthole'
  }
}


if (user()) {
  const gottenUser = user()
}

This doesn't make sense in human language. This is not how we read sentences. While this is a small example, if you have an entire project written with such disregard for human language grammar, it will quickly become confusing. It will take you much more brain power to keep in mind what's what.

How I would fix that code:

function hasUser() {
  return true
}
function getUser() {
  return {
    id: '1',
    name: 'Mr. Poopy Butthole'
  }
}


if (hasUser()) {
  const user = getUser()
}

What did I change?

First, I introduced a new function for the if statement. It returns a boolean, which makes it clearer in itself, but also the name indicates that it returns a boolean. How? Try and make it a question: Has User? The answer is yes or no - boolean!

Second, I renamed the user() function to getUser(). Since functions are actions, it is only appropriate to use verbs for function names.

Third, I could use the now-available noun for the variable. That again makes more sense, since variables are objects, thus should generally be nouns.

Try to read that code like English now. Can you quickly understand what's happening? I don't doubt you do.

Rules

One Rule To Rule Them All:

You must be able to read your code like English the day after.

If you can't, you screwed up, redo it.

Now, I'm not saying that you have to keep writing and reading and re-writing and reading and re-writing ... until it feels right. There's a pretty clear set of rules that'll help you get it right. In fact, these rules will also help you have clear separation of concerns, which is just a win-win! Here we go:

Always name your functions with verbs.

Avoid function names such as user() or post(), especially avoid the temptation to make them handle the entire CRUD. Instead, introduce actions on objects: getUser(), addUser(), modifyPost(), deletePost(). Right away you see what each function does.
Describe what function does in the name, yet limit it to 1-2 verbs

This is a tricky one. Always include everything your function does in the name. If your function creates a user and sends a welcome email, name it createUserAndSendWelcomeEmail(). You might see even with 2 verbs this is getting long. This is a sign for you to split it into 2 functions: createUser() and sendWelcomeEmail(). Then you can emit an event from createUser that sends a welcome email.

This achieves 2 goals. First, it makes obvious what your functions do. Second, it forces you to split your functions by concerns and keep them short!
Always name your variables with nouns and add adjectives where necessary

Your variables contain data, or objects, which in English are described by nouns. Thus, to make your functions that act on your variables (objects) clear, your variable names have to be nouns. users or posts are acceptable.

With that in mind, always include relevant adjectives in your variable names, especially if you have more than 1 with the same data type in one context. For example, you fetched all posts and then filtered the ones written by Mr. Poopy Butthole. Instead of having posts and posts2, you should have allPosts and postsByPoopy. It makes a huge difference!

These rules are foolproof. Follow them and you will inevitably produce readable code.

How about a bad and good example of these rules?

// ❌ BAD

function users(id) {
  if (id) {
    return userByIdFromDatabase(id)
  } else {
    return allUsersFromDatabase()
  }
}

function posts(post, userId) {
  if (!post) {
    return allPostsFromDatabase(userId)
  } else {
    return updatePostInDb(post)
  }
}

const user = users('1')
const postsFromDb = (null, user.id)
const posts2 = postsFromDb.filter(post => post.author === 'Mr. Poopy Butthole')

posts2[0].title = 'I write bad code'
posts(posts2[0])

// ✔️ GOOD

function getUserById(id) {
  return getUserByIdFromDatabase(id)
}
function getAllPosts() {
  return getPostsFromDatabase()
}
function updatePost(id, post) {
  return updatePostInDatabase(id, post)
}

const user = getUserById('1')
const allPosts = getAllPosts()
const firstPostByPoopy = allPosts.filter(post => post.author === 'Mr. Poopy Butthole')[0]

updatePost(
  firstPostByPoopy.id, 
  {
    ...firstPostByPoopy,
    title: 'I write good code!'
  }
)

What a difference! The first example is impossible to read in English, function names are ambiguous and do not reflect what they do. The second example is totally different though! The functions and their purposes are clear, each variable is understandable and I'm sure it takes you no time to read.

As I mentioned in the beginning, I have been a part of different teams and have built one. Having readable code helped us each time to hire good developers that don't have experience with our specific tools (which is especially important in JS with its variety of standards and frameworks). Approaching code like human language will allow your new developers to spend time being productive instead of trying to understand what you wrote.

Do you have any other good readable code practices? Let's discuss it in the comments!

You Might not need Redux

Jaff Parker — Tue, 07 May 2019 16:45:19 +0000

Redux is an awesome state management library. While being very minimalistic, it offers the structure and order that can easily be neglected in a React project. That's why I would automatically install it every time I start a React project. It would be my cache, my application state keeper ~~and best friend~~.

Then I discovered Apollo Client that can manage cache for you without much overhead. That's when Redux' role was starting to reduce (pun intended) in my dev experience. Basically, I would only use it for authentication and network/server state.

And then React released hooks, including the useReducer one, whose usage reminded me a lot of Redux... At this point I started to rethink whether I really need an entire extra dependency in my code to manage very little.

In this post I will describe my reasoning behind moving away from Redux and go through the process of migration. Hopefully it can help some of you keep an open mind about your favourite libraries and realise when it might be time to let go of them :)

Why leave Redux?

There are a few reasons that pushed me into exploring replacing Redux with hooks API.

First, I was installing an extra NPM package for just 4 actions and 2 states. That seemed very excessive and added complexity to the project. Besides, React offers everything you need for basic app state management. If you don't use it, it's a waste of code.

Second, I was starting to get annoyed with how complex typing connected components can get... I had to write a whole lot of extra code sometimes just to know whether the user is authenticated or not.

Third, like many, I instantly fell in love with React hooks and how well they tie into functional components (my second favourite thing in frontend dev after hooks themselves).

How did I leave Redux without breaking anything?

My Redux store had 2 reducers combined: auth and appStatus. First, let's see how I migrated auth.

auth state was simple:

interface AuthState {
  isSignedIn: boolean
  token: string
  user: User
}

With it came 2 actions: signIn and signOut.

First thing that I noticed is that React's useReducer hook has the same reducer signature as Redux. So the great thing is that you can totally reuse your reducers! However, I could not just put reducer in a context. I needed to be able to update it from the nested components, so I followed the tutorial from the official docs called Updating Context from a Nested Component (what a coincidence??). Thus this code was born:

// contexts/AuthContext.ts

export const AuthContext = createContext<AuthContextState>({
  isSignedIn: false,
})
export const AuthProvider = AuthContext.Provider

// components/AuthContextContainer.tsx

import {
  auth,
  signIn as signInAction,
  signOut as SignOutAction,
} from '../reducers/auth.ts'

export const AuthContextContainer: FC = ({ children }) => {
  const [state, dispatch] = useReducer(auth)

  const signIn = useCallback((user: User, token: string) => {
    dispatch(signInAction(user, token))
  }, [])
  const signOut = useCallback(() => {
    dispatch(signOutAction())
  }, [])

  return (
    <AuthProvider value={{ ...state, signOut, signIn }}>
      {children}
    </AuthProvider>
  )
}

Bam! There's the Redux auth store. Now to use it in my components instead of connecting them, I simply had to do this:

export const SignInContainer: FC = () => {
  const { signIn } = useContext(AuthContext)

  const onSubmit = async ({email, password}: SignInFormValues): void => {
    const { token, user } = await getTokenAndUserFromSomewhere(email, password)
    signIn(user, token)
  }

  return (
    // ... put the form here
  )
}

Now I can sign into the app and browse around! What happens though when I reload the page? Well, as you might've already guessed, the app has no idea I was ever signed in, since there's no state persistence at all... To handle that I modified the AuthContextContainer to save the state into localStorage on every change:

export const AuthContextContainer: FC = ({ children }) => {

  // LOOK HERE
  const initialState = localStorage.getItem('authState')

  const [state, dispatch] = useReducer(
    auth,

    // AND HERE
    initialState ? JSON.parse(initialState) : { isSignedIn: false },
  )

  const signIn = useCallback((user: User, token: string) => {
    dispatch(signInAction(user, token))
  }, [])
  const signOut = useCallback(() => {
    dispatch(signOutAction())
  }, [])

  // AND HERE
  useEffect(() => {
    localStorage.setItem('authState', JSON.stringify(state))
  }, [state])

  return (
    <AuthProvider value={{ ...state, signOut, signIn }}>
      {children}
    </AuthProvider>
  )
}

Now the useReducer hook gets an initial state and it's persisted on every change using the useEffect hook! I don't know about you, but I think it's awesome. A component and a context do exactly what an entire library used to do.

Now I'll show you what I did with the appStatus state. appStatus only had one job: watch for the network availability and store whether we're online or offline. Here's how it did it:

export const watchNetworkStatus = () => (dispatch: Dispatch) => {
  window.addEventListener('offline', () =>
    dispatch(networkStatusChanged(false)),
  )
  window.addEventListener('online', () => dispatch(networkStatusChanged(true)))
}

export interface AppStatusState {
  isOnline: boolean
}
const defaultState: AppStatusState = {
  isOnline: navigator.onLine,
}

export const appStatus = (
  state: AppStatusState = defaultState,
  action: AppStatusAction,
): AppStatusState => {
  switch (action.type) {
    case AppStatusActionTypes.NetworkStatusChanged:
      return {
        ...state,
        isOnline: action.payload.isOnline,
      }

    default:
      return state
  }
}

You can see that to watch for network status, I was using a thunk, which isn't offered by the useReducer hook. So how did I handle that?

First, like before, I needed to create the context:

// contexts/AppStatusContext.ts

export const AppStatusContext = createContext({ isOnline: false })
export const AppStatusProvider = AppStatusContext.Provider

Then like for auth, I started writing a container that will handle the logic. That's when I realized that I don't even need a reducer for it:

// components/AppStatusContainer.tsx

export const AppStatusContainer: FC = ({ children }) => {
  const [isOnline, setIsOnline] = useState(true)

  const setOffline = useCallback(() => {
    setIsOnline(false)
  }, [])
  const setOnline = useCallback(() => {
    setIsOnline(true)
  }, [])

  useEffect(() => {
    window.addEventListener('offline', setOffline)
    window.addEventListener('online', setOnline)

    return () => {
      window.removeEventListener('offline', setOffline)
      window.removeEventListener('online', setOnline)
    }
  })

  return <AppStatusProvider value={{ isOnline }}>{children}</AppStatusProvider>
}

Thus I not only got rid of an extra dependency, but also reduced complexity! And that particular thunk could simply be replaced with a useEffect hook.

That's how in a few short steps (and about an hour) I managed to reduce the size of my app bundle and get rid of some unnecessarily complex logic. The lesson here is that no matter how useful a library can be, it can and will happen that you don't need it. You just gotta keep and open mind about it and notice when it happens :)

I hope my experience will give some of you the courage to try new things and discover new dev experiences for yourselves!

PS: hooks are awesome! If you still haven't, you should totally start using them.