Writing code for others

Have a look at the following code. How does it make you feel?

<Field
  type={intDur}
  res={res}
  onUpdate={calcDur}
/>

This component could contain the best code ever written. The gods of code could have passed it down, chiseled into a stone tablet, it would still suck.

res could be short for response, result, resource, resume, reset, reserved, restore, resolve..

Naming things is hard, but there’s a way to make it infinitely better:

Don’t name things for yourself or the computer! Name things for your colleagues!

It’s a 1-step program:

Naming functions:

Name functions by what they do. It doesn’t matter if the names get long, the bundle won’t get any larger. These will all be minified into oblivion.

How much better is findBookWithHighestRating() than topBook() ?

Some examples:

⛔️ Not cool!

authArr(input){…}

✅ Cool!

groupBooksByAuthor(books = []) {…}

⛔️ Oh god, what?

calcDur(d1, d2) {…}

✅ I understand now!

calculateDurationBetweenDates(dateA, dateB) {…}`

Naming variables:

Name variables in a way that describes what they are. Seems obvious, but don’t make it shorter for no reason.

These should also be minified for production, so why not be kind to yourself and your colleagues in development?

⛔️ NO!

const cmp = {};

⛔️ Still no!

const computed = {};

⛔️ What value though?

const computedValue = {};

⛔️ Better, but still confusing.

const computedAge = {};

✅ There we go!

const ageBasedOnTodaysDate = {};

There are cases where you don’t have to be so explicit, it depends on the situation. For example, if the above variable was defined and lived within the following context, it would be fine to give it a simpler name:

const age = calculateAgeBasedOnTodaysDate();

Naming components:

You’ll probably end up with several components that deal with different aspects of something, for example, if you were working on a website for a library:

• A component that displays a book
• A component that lets you edit a book
• A component that displays a list of books

You could call them Book, EditBook and BookList, that’s a start. Then you realise you need a component for editing a list of books. Okay, that’sEditBookList. Whether you like folders or not, I think a better way to name components like this is:

[domain][component][modifiers]

All “Book”-related components would live in the “Book” domain, so we might end up with a list like this down the line:

├──/Book
├──/BookEdit
├──/BookList
├──/BookListEdit
└──/BookDetails

If you’re a folder-person, you could of course do it like this:

└──/Book
   ├──/Edit
   ├──/List
   ├──/ListEdit
   └──/Details

Regardless, now it’s pretty easy for anyone to quickly scan the components-folder (or use the jump-to-file function) and see everything related to books.

Long vs short names

I’m not saying every function needs to be a camelCased sentence, shortening words is fine, as long as it’s still understandable.

calculateDurationBetweenDates could be calcDateDistance.

If you put all date-related helpers in a single file, you could also remove any references to “date” in the function names as this would be implicit from the import.

Import { calcDuration, addDays } from “./helpers/time”;

Wrapping up

Naming things is something new developers often do better at than seniors.

Yes, I’m sure “invertArgSuffix” is a good representation of what the computer does, but the computer doesn’t need this information, it’ll parse your code regardless. Call it something else!

Write function names for humans.

Write variable names for humans.

Write code for humans!

Chances are unless you’re working on a hobby project, someone else will spend time looking at every word you type. You’ll need to understand the code yourself when you come back in 6 months time.

Someone will probably scoff at some bad code you wrote years ago, that’s fine, as long as they understand it.

It doesn’t have to be good code, don’t worry about that, everyone writes bad code all the time. Just make it readable.