Writing Code That Makes Your Teammates Lives Easier

Working alone =/= working in a team. There might be things in your code now that might not be as easy to understand for other developers, including your future self. This is not about spending an hour automating a boring task. These tips are simple trivial changes. Simple enough that you wouldn’t have to rewire your brain or change your workflow 👍

PS: This is a cross-post from my blog.

tl;dr

• Write good commit messages
• Add comments to hacky implementations
• Write self documenting code / variables / methods / classes instead of adding comments

PS: These tips have been helpful with me getting on and off with my side projects for long periods of time. I used to spend an hour or two getting back up to speed with my side projects. Now it only takes about 15 minutes!

PPS: Writing a good README with installation and usage guide helps :)

Write good commit messages

Commits are great are providing context about the project. In an ideal world, one could look into the history to understand why certain changes were made and how.

don’t:

- Refactor
- Fix bug
- Fix bug
- Cleanup
- Remove test [0]
- Add feature

Many things wrong here. What did the programmer refactor? What bug/s were fixed? What was cleaned up? What test was removed? What feature was worked on?

[0] When I inspected closely what test was removed, it turned out that it meant a ‘test’ word that somehow snuck in some css file as opposed to an actual test removed.

do:

- Refactor for loop to use .filter
- Handle edge cases
  - Don't empty cart when user logs out
  - Prevent crashes when more than 3 tabs open
- Remove redundant and unused code
- Implement feature X

This style of writing commits shares a living diary of the project. This makes it easy for anyone to find relevant changes just by looking at the logs (ex: git log). Chris Beams wrote a great piece on how to write commits.

Add comments to hacky implementations

What is bad about hacky code is that it is often undocumented and invites other developers to build on top of it. It becomes something that no one understands or knows about. Newer members of the team will try to avoid touching this code as much as possible and attempt to work around this code.

don’t:

my-class {
  ...
  flex-direction: column;
  ...
}

Our little hacky code could into something bigger and badder. It might not be obvious what it’s for and if it’s still relevant today. Working around it will eat up precious development time.

do:

my-class {
  ...
  flex-direction: column; // hack to center overflowing text in IE 10 https://stackoverflow.com/a/42302827
  ...
}

Months, or years down the line, your project might not even support IE 10 anymore. We can now remove this hack, and now we don’t have to worry about this hack’s other side effects.

Write self documenting code / variables / methods / classes instead of adding comments

Easier to read methods when accessed in a different class. Otherwise, user of API will have to read into the method/class to understand what it does. This is unnecessary and a waste of time!

dont:

void main() {
  play = true
  board = board()

  while (play) {
    input()
    play = win()
  }
}

do:

void game() {
  isPlaying = true
  initBoard()

  while (isPlaying) {
    getUserInput()
    playing = !hasWon()
  }
}

You can easily tell that the game() method initiates the game, prepares the game board, gets user input, and ends the game if the user has won.

The same applies to variable names.

dont:

// Updates the UI
void updateUI() { ..

// the data store
var store = ..

These comments add nothing to my understanding of what this variable is for. updateUI() -should- update the UI, etc.

do:

void updateUI() {
}

var store = Store()

Read this post for a more thorough reading on naming variables.