DEV Community: Manuel Bieh

Omfg books have tech stacks now: how I used web technologies to layout and print a book

Manuel Bieh — Sat, 10 Aug 2019 12:41:09 +0000

Sorry for the title, I just had to quote Kitze here:

// Detect dark theme var iframe = document.getElementById('tweet-1151731672582434821-486'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1151731672582434821&theme=dark" }

A few months ago, in April 2019, I published a book about React. It's a technical book. And by saying that, I mean it's a technical book in a number of ways. Sure, the content is all about React, how React works, how you build components and applications with React. In that way, it's a technical book like any other.

The more interesting aspect is the second way in which it is a technical book: namely, the way it is produced.

The writing phase

I used an early version of the great new version of gitbook.io because it's meant to be used for technical articles and texts, like documentation or ... books. At least that's what you might think when you take a look at their name.

Well, as it turned out, although it's indeed great for writing comprehensive documentation in a very nice and easy way, it's not really intended to be use to write actual books. By the time I was writing the book, there wasn't even a way to export your Gitbook as PDF or any other format like ePub (and I'm not even sure there is an official way today). What they instead do is to publish a beautifully designed HTML version which is stored entirely on GitHub as Markdown files with a few custom enhancements.

I didn't know how difficult it is to turn your Gitbook into an actual book until I wrote ~120 pages and neither did I want to go back to Google Docs or Word for writing as it's still a technical book with a lot of code examples and they really don't look great in Word docs.

The fun part

So I did what developers do when they have other more important things to do: I procrastinated and built my own toolset and tech stack around my book.

I cloned the GitHub repo of my book. I installed Showdown and the Showdown Highlight plugin to convert the Markdown source files into HTML, with beautifully styled code examples. I even used Prettier to automatically format the code examples within code blocks! I then combined all converted files into one giant HTML file.

I then added Puppeteer to the stack. This allowed me to to convert the Markdown files I converted into HTML earlier into a PDF very easily. Since I used HTML as source format for conversion, I was able to use CSS to style the whole book! Puppeteer is really great at converting HTML files into PDF with a fairly good support for CSS Print features (well, sometimes more, sometimes less good). This way I was able to layout and style the PDF (which I later sent to the print shop!) pretty much exactly how I liked it.

For the ePub version I decided to use the fantastic Pandoc. Pandoc allows you to convert many different text based formats (Docx, HTML, Markdown, ...) into other formats like ePub. Writing CSS for ePub feels a little bit like building email templates. That's really something you don't want to customize too much because you have no guarantee that your ePub will look exactly how you want it to look in every client. So I only used as little custom CSS as necessary.

Hacks and caveats

The whole process was a bit tricky and required a few hacks (as always, huh?) and it also comes with a few caveats. For example I'm unable to add page numbers to the TOC in the PDF, because by the time I am generating the TOC, I don't know the page numbers, as they will be automatically added by Puppeteer later in the final PDF conversion step.

The CSS orphans and widows properties also seem to not work properly or at least not how I would have expected them to work. And my impression is that break-* properties also cause some unexpected behavior sometimes. Not beautiful, but neglectible for me.

In general though, I am really happy about the result: a book, written in my web browser, stored as Markdown on GitHub and converted into a real printed book completely based on web technologies!

The code is still a bit hacky, I never really cleaned it up, but if you're interested in reproducing it, or even want to convert your own Gitbook into a nicely styled PDF, you can find the code on GitHub: https://github.com/manuelbieh/gitbook-pdf-converter

Here's a small impression how the result looks like in the end:

I refuse to work in teams without a proper code review process - and you should too!

Manuel Bieh — Mon, 20 May 2019 11:51:33 +0000

When I'm doing client work as freelancer I refuse to work in teams without a proper code review process. I want to tell you the reasons but first of all let's have a look at my definition of what a "proper code review process" actually is:

Every feature, bugfix, hotfix or whatever is developed on branches (feature, developer, … up to you). No code is ever directly pushed to the master branch!
In fact, your main branch(es) should be protected and merging changes into master (develop, …) require at least one approval by one of your colleagues
Everybody in the team (from trainee to lead) gets and regularly takes(!) time and is even encouraged to do code reviews
Reviews are taken seriously by everyone involved! No thoughtless clicking of the "approve" button without actually having reviewed the code. If your chosen reviewer does not have any bandwidth now remind him to do that later or ask another colleague if it's urgent.
Pull requests that still require review don't "pile up" because "there are more important things". It's okay to have a few pull requests open at the same time but you should not have 50 open PRs in a team of 5 developers. From my experience 2-3 open PRs per developer at the same time should be fine and still manageable to review properly but that of course depends a lot on the size of the PRs.
Pull requests are kept short. 15-20 files in a React project should be the maximum for a PR. Sometimes you can't avoid that but please at least try it.

I refuse to have my code merged into master (and as a consequence sent into production afterwards) without review for several reasons:

Maintainability! 🍎 Code that looks super clear to me, might look super confusing to others. Reviews can (and usually do) help a lot here to make complex parts simpler.
Liability! 📜 If I commit a super obvious bug that for whatever reason is not covered by tests and it goes into production I am the only person responsible for that misfortune. Having it approved by someone else can split this responsibility in half (or even more). Especially when you're a contractor (like I am) who can be held liable for negligence, such a review can be crucial and literally save your butt one day. (I say can, not will!)
Documentation! 📋 I usually write a short but understandable description of what's happening in my PR. If later you (or anybody else) is unsure about something you might find the answer in old pull request descriptions if it's not explicitly mentioned in the docs/readme.
Sustainability! 🌿 A codebase where everybody can just commit unreviewed code carelessly usually looks exactly like that: like nobody cares. That's not sustainable and will inevitably end in a desaster eventually.
Risk reduction! 🛡 Sometimes you're working on a relatively complex feature mostly alone for several days. By having another person reviewing your code, this person inevitably gets an idea what this is all about. That can already reduce your bus factor tremendously.
Learning! 🎓 As a developer you can only grow by receiving and giving(!) feedback to code regularly. Code reviews are a great way to discuss alternative solutions and different approaches to the one you went with and let you suck free knowledge out of other people's brains.

Doing a good code review takes time. The best companies I've worked with had really "time consuming" review processes but it is time that is really well invested! The time you lose by being "slower" today is very likely saved by orders of magnitude in a long term codebase at a later point!

Using Windows 10 For Serious Web Development - A Quick Starter Guide

Manuel Bieh — Tue, 07 May 2019 03:49:35 +0000

It's pretty funny because every other developer I meet is always wondering and asking me if (and how) it is really possible to work on a Windows machine as a JavaScript/Frontend Developer. And hell yeah, it is!

Let's start with a little bit of my personal history first.

I've been using Windows basically all my life (let's ignore C64 and Amiga 500 here). First I used my dad's Windows 3.11 machine from his work to play Minesweeper (without actually understanding how it works (which I still not do)). Later when I was 11 or 12 I got my first very own Windows 95 PC. Shortly after, I got a bit into gaming and so buying a Mac was not really an option for me. Not to mention that they were (and are) not affordable when you're 14-15 y/o and still going to school.

When I stopped playing games I was still in school so I still couldn't afford a Mac and when I later got my first real job in 2002, they provided me with a computer which was also running on Windows. I seriously considered switching to Mac in 2008 but I was doing a lot of hobby photography and image editing back then and I was using a legal(!) (student) copy of Photoshop which was valid for Windows only so I didn't make the switch. Thank you, Adobe!

I was thinking about switching to Mac again in 2013 (and I even bought my very first own Mac, a MacBook Air) but still sticked with my Windows PC for reasons I cannot recall.

And that's where I am today. I'm still using Windows as my primary operating system for my every day life as Javascript Developer and even though I learned how to type an @ on a Mac keyboard now, I'm not thinking about switching to Mac anymore. At least not anytime soon.

I have a keyboard that's working, a great selection of viable hardware and all that for a mostly reasonable price. Windows 10 keeps getting better and better, Microsoft has been doing an amazing job in the last couple of years and continues to do so.

So let's get back to the initial question: how is it possible to work on a Windows machine as a JavaScript Developer?

First things first: use the Professional Edition

Many PCs come with a Windows 10 Home Edition which is kind of useless for professionals because you have no support for Hyper-V which you need to use Docker and also no support for WSL, the Windows Linux Subsystem. So first of all: get the right version. If you bought a Windows PC with Windows 10 Home, don't worry: you can upgrade through the Windows Store pretty easily. I've done that once, don't remember how I did that but what I do remember is that it took me one Google search, five clicks and 15-20 minutes of my time and my system was upgraded from Home to Professional. So it's really easy.

Tools

That's the most essential part. The tools on Mac like iTerm or Homebrew are incredible. Windows can't quite keep up with that but there are alternatives which are - in my opinion - at least almost as good as their macOS equivalents.

Cygwin

Let's start with the console. Forget Powershell or the Windows Command Shell (cmd). I'm spending a fair amount of my time on the CLI and I haven't used either of them for years. Use Cygwin! It's a compatibility layer and gives you (their own words) "that Linux feeling on Windows". You cannot run native Linux binaries in Cygwin but the project ported a whole bunch of Unix tools to Windows and from my experience most of them look and feel like their native Unix counterparts. You even have a home folder which you can access just like on linux by typing cd ~ into your Cygwin CLI, you also have ls and cat and even rm (careful!).

Download the installer, run it, select a mirror to download the package list from, select all the Unix packages you like (e.g. vim or nano, openssh, wget, curl, …) and go! Do not install Git though. We'll do that manually later. There's Git for Windows which integrates better and causes less stress.

Hint: Unlike Linux, Windows is not case-sensitive when it comes to files and folders. I avoid to have spaces in paths and try to keep all paths lowercase to not get into trouble when working with the WSL Linux Shell or Git. My Cygwin installation is located in C:\cygwin64 for example. It can save you some additional headache.

Once Cygwin is installed, I recommend to install apt-cyg which, you might have guessed it, works pretty similar to apt-get on Debian. Once it's downloaded to your home folder (C:\cygwin64\home[username]) you can install packages as easy as apt-cyg install curl.

Note: Cygwin adds its bin folders to your system's PATH. If the system PATH is modified you must usually close all cmd.exe, powershell.exe, bash.exe and explorer.exe processes and restart them to have the updated PATH available everywhere. The easiest way is usually to restart the whole system (hey, it's still Windows …).

// edit: you can type refreshenv in your cmd, as @AkosLukacs pointed out!

95% of my everyday tasks when doing Node.js or React development work perfectly fine in Cygwin and they look and feel almost like a real Linux. Webpack, Yarn, NPM, Puppeteer, Node. I even regularly ssh into different servers using Cygwin's openssh.exe. You can mkdir ~/.ssh and put all your ssh keys there. Cygwin/openssh will automatically look for the keys if you try to connect to a server via SSH, just like on Mac or Linux!

I think Cygwin is responsible for not having missed a real unix based machine over all the years.

Windows Subsystem for Linux (WSL)

Sometimes (really rarely, at least in my case) the tools Cygwin provides aren't enough. Then it's time to install Windows Subsystem for Linux. It's a real Linux environment that's running on your Windows machine. Once you enabled the feature in the Control Panel you can choose your distribution from the Microsoft Store and run almost everything you can run on native Linux machines, except for GUI applications (although there are people who got this working). Currently you can choose between Ubuntu, Debian, SUSE, Kali, Pengwin and Alpine.

Caveat: By default all files and folders have root as owner and chmod 777 which, you know, is quite bad. You have to remount your drives to be able to use proper files and folders permissions. Read here how you can do that:

WSL also comes with a binary called bash, exactly like Cygwin. To avoid confusion I added an alias for the WSL bash to my ~/.bash_profile:

alias lx=/cygdrive/c/Windows/System32/bash.exe

This allows me to type lx to start the WSL bash when I'm in my Cygwin bash.

/cygdrive/c/ is where all your file are, Cygwin mounts your drive to a unix-style filesystem where /cygdrive/c is equal to C:\\ in Windows.

Git

As I mentioned before, it sometimes leads to weird behavior and incompatibility between different programs when using the Git binary that comes with Cygwin so you better download Git for Windows.

The options during setup can be a bit overwhelming if you're new to Windows. You do not need the Windows Explorer Integration (we're using Cygwin with ConEmu here later) so you can go with the default components in the first screen. In the next screen you can select your favorite editor to use with Git. I go with the default which is nano because I never understood vim like so many others. Feel free to choose something else.

In the next screen you want to use "Git from the command line and also from 3rd-party software". And you want to use OpenSSH instead of TortoisePlink. The next important option is the line-ending conversion. Checkout as-is, commit Unix-style line endings (core.autocrlf=input) is what you want here or otherwise your colleagues get mad at you because GitHub marks all changes in line ending style as a change in Pull Requests. That's ugly and you really don't want that.

As terminal MinTTY is probably a better choice than cmd although I never use it anyway because of Cygwin. On the last screen, Extra Options, you should check all three: file system caching, git credential manager and symlinks. Once it's installed you can use all the commands you're used to. You can even put a .gitconfig file into your home folder in Cygwin and modify all your settings there. It also respects your ssh key in ~/.ssh - just like on Linux or Mac!

Terminal: ConEmu or Cmder

macOS has iTerm, which is beautiful but Windows has ConEmu and Cmder (which is using ConEmu under the hood). Personally I'm using ConEmu and it's just great. It gives you a lot of keyboard shortcuts, supports tabs for your console windows and just provides a lot of functions and features for your convenience. It's not quite as beautiful as iTerm but it offers a very similar functionality. I've setup ConEmu to be my default terminal application and within ConEmu I've made Cygwin's bash.exe my default shell. Cygwin detects all installed shells automatically and you can select the shell of your choice from a drop down menu!

You can also register ConEmu as menu option for files and folders and so every time you right click a file or folder anywhere in Windows you can select "Open ConEmu here" to start a new terminal Window pointing to the selected path. You can find it in the ConEmu settings in the "Integration" menu.

IDE/Editor

I'm using VSCode as my primary editor/IDE for development. Since VSCode is from Microsoft it works perfectly fine without any issues on Windows of course (who would've guessed?). If you want to use the integrated terminal with bash.exe from Cygwin (which I do, and I love it) you might first have to adjust a few settings though:

"terminal.integrated.shell.windows": "C:\\cygwin64\\bin\\bash.exe",
"terminal.integrated.env.windows": {
  "CHERE_INVOKING": "1"
},
"terminal.integrated.shellArgs.windows": [
  "-l"
],

This makes it possible to open the terminal in VSCode and having it pointed to the current project's root folder. It works very similarly in Atom which I was using before switching to VSCode.

If you're using Windows 10 Build 18309 or newer you can also set:

"terminal.integrated.windowsEnableConpty": true,

This makes VSCode use ConPTY instead of Winpty. Rich Turner tells you more about that.

Node.js

If you're working with Node.js, I recommend to use nvm-windows to install it. It works pretty much in the same way as nvm does on Unix based machines but a few commands are a little different (e.g. nvm list available instead of nvm ls-remote).

Download the installier from GitHub, install the tool and you can install Node.js from your commandline by typing nvm install 10.15.3 && nvm use 10.15.3.

Upgrading the pre-bundled npm version can sometimes be a bit tricky though. Many users (me including) are reporting a weird issue here. I worked around that by installing yarn globally (npm i -g yarn), adding yarn's global bin folder to the PATH (you can find it using yarn global bin) and installing npm via yarn global add npm. Works fine. Just make sure that the yarn bin folder has precedence over npm's bin folder (so move it higher up in the path).

Next you will need to install the Windows Build Tools. This allows you to install packages which need to be compiled/built on your machine using node-gyp. That's one of the really rare occasions where you really need Powershell. And you need an elevated Powershell with Admin permissions. In ConEmu you can press [win]+[shift]+[w] to open a "Create new console" dialog. There you can select Powershell and tick the "Run as administrator" checkbox at the very bottom of that dialog. If you're not using ConEmu, you can press [win]+[x] to open a menu from which you can start a Powershell window as Administrator.

Once the console is open, run yarn global add windows-build-tools. This might take a minute or two.

Docker

That's an easy one. There is Docker for Windows. Install it, run it, be happy.

Well, not quite. You need to have Hyper-V enabled first. Here is how you do that.

Attention: If Hyper-V is enabled, Virtual Box versions older than 6.0.0 don't work anymore. If you need Virtual Box 5.x you can't use Docker at the same time. Hyper-V and Docker or Virtual Box 5.x. Choose one.

Emojis

Very important, especially when you're coming from macOS. Emoji support on Windows is still pretty new and, admittedly, their Emojis are just plain ugly. In most applications you can press [win]+[.] to open an Emoji picker. It works great in "modern" applications like Chrome or VSCode, it works not so great (or even not at all) in other applications like the terminal, Notepad or WordPad.

Other unrelated tools

Tools that are worth taking a look at to improve your experience with Windows even more:

Groupy - to organize your windows into tabs.
IrfanView – great freeware to open (and convert) all different types of images
Notepad 2 – as powerful, lightweight and fast replacement for Windows' native notepad.
LockHunter – to find (and exit) processes which are locking files

There are probably many other things to know and do when you're setting up a Windows PC to use it for software development which I didn't mention here. If you have any questions, get in touch with me!

How to Make Your Team and Your JavaScript Project Better in 2019

Manuel Bieh — Mon, 01 Apr 2019 17:18:27 +0000

This article was published on Medium a few weeks ago. Since I'm saying good bye to Medium I am reposting it here.

When I join a new project (which happens quite often since I’m working as an independent freelance developer) I usually have a look at the current project setup first. It’s a good way to get a quick overview of how the project is organized, what tools they’re using or most of the times, unfortunately, they are not using.

I like clean, thoughtful and well-designed setups and processes a lot and I appreciate a healthy and sustainable code base as it makes working with your company’s code a lot easier, a lot less painful and it makes your developers faster in the long run since it results in a much more maintainable code base.

So when I have a look at your package.json for example there are a few things I’d like to see there and I would really recommend and encourage you to somehow integrate them in your workflow. They might be hard in the beginning and sometimes your developers will curse for a moment but trust me once you’ve done that and you got used to it there is no way back.

The Tools

Let’s start with a tool that was (and still is) controversely discussed in the dev community. It seems like you either love it or you hate it. I was in the second group at first and I’ll explain why in a bit. I’m talking about Prettier.

Prettier

It’s a tool that formats your code in a completely unified way. You can either use the Format on Save option in your IDE, format it manually, or even create a Git hook to format all files that are being committed automatically.

// Detect dark theme var iframe = document.getElementById('tweet-1007516466139234304-438'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1007516466139234304&theme=dark" }

Many developers I talked to who disliked Prettier said that they want to have control over how their code is formatted and that they often disagree with how Prettier formats code. As mentioned in the beginning, that was also me in the beginning. Until I found the true value of the tool.

Most of the time it is not about you, but about your colleagues.

Ever wondered about that super strange coding style your colleague uses when formatting code? The same thought you have when reading that colleague’s code, your colleague will very likely have when he’s reading your code, ever thought about that? Won’t happen with Prettier.

Prettier has only very few options and formats your code based on some really sophisticated rules. They are open to new PRs, too. While you won’t always agree to how Prettier thinks your code should be formatted it’s freeing up so much mental energy, believe me.

// Detect dark theme var iframe = document.getElementById('tweet-1052154040765898755-10'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1052154040765898755&theme=dark" }

Spend your energy on thinking about what to write and not how to write it! Write it however you like, hit CTRL+S and watch Prettier do its job. It really frees up so much mental energy. I’d say it has probably become the most valuable tool in my developer toolchain since switching to Git in 2010.

// Detect dark theme var iframe = document.getElementById('tweet-1037178073966362625-574'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1037178073966362625&theme=dark" }

Another clear plus: we can end the debate whether to use semicolons or not and if 2 or 4 spaces is the right level of indentation. You can delegate that decision mostly to a computer program and write the code exactly you feel is right for you.

So my recommendation here, if it has not happened yet: add Prettier to your projects! Even more: have your files automatically run through Prettier to make sure that even colleagues who still refuse to use it in their IDE push their code in a way everybody can read. I remember that one colleague who refused to use it and later committed mock data for tests with an array of 25 objects. All. In. One. Line. No. Don’t be that guy, please.

Which leads us directly to our next candidate:

Husky, lint-staged and install-deps-postmerge

Husky simply describes itself in its readme with:

Git hooks made easy

And yup. That is what it is. It makes writing Git hooks a bliss! No more shell scripts that work only on your machine, no more need to install ruby or python only to run a certain Git hook. Install Husky, create a .huskyrc file and put a few simple commands in there.

Husky works especially great in combination with lint-staged and install-deps-postmerge. lint-stage runs linters against all your staged files allowing you to modifiy files before they are eventually pushed to GitHub. install-deps-postmerge on the other side runs after you merged files from remote (e.g. via git merge), then checks your package.json and your lockfiles (yarn.lock, package-lock.json) for changes and automatically updates your dependencies.

In my typical setup I use it to automatically have all my staged files run through Prettier before they land on GitHub. That’s typically a pre-commit hook I add. Another one is an ESLint check which lets your commit fail to avoid having potentially harmful code in your code base. Which leads us to our next very useful tool.

ESLint

It’s hard to imagine that there are still teams out there not using ESLint in their JavaScript projects but believe me, there are. I don’t even care that much about what rules exactly you use and how you configured them but you should at least cover the most common mistakes that can lead to serious bugs in your code (like no-redeclare, no-undef or many many others).

If you can catch bugs at devtime instead of runtime, why should you not do that? I created my own personal eslint-config and published it as a package on npm. A client asked me to take a day to figure out which rules make most sense in their React project back in 2016 and so I created my very own package from this newly acquired knowledge with all the rules I found helpful. You can find it here: https://www.npmjs.com/package/eslint-config-wiremore

Although I’m really trying to keep it up-to-date on a regular basis there might be ESLint configs that are even better and more regularly maintained than mine. I can really recommend to have a look at the eslint-airbnb-config for that matter.

ESLint integrates really well with Prettier by the way. So together they’re a great combination.

cross-env and dotenv

When I develop software I am following the 12 factor methodology. This is something I recommend all my clients as that makes your software predictable, maintainable and understandable. Part of that methodology is to III. store config in the environment. And by environment, of course, environment variables are meant.

This is where cross-env and dotenv come into play. Both tools are designed to make your life as a developer easier when it comes to dealing with env vars. cross-env as the name indicates let’s you use env variables on all different platforms (Windows, Unix, Mac) without having to think about special syntaxes, try to detect the OS or terminal the user is using etc. Just prefix a command you want to run with cross-env followed by the env variable(s) you want to set and you’re all set.

$ cross-env HELLO=world node -e 'console.log(process.env.HELLO)'
> world

The other tool, dotenv, is for pulling all the env vars into your application at runtime (node) or build time (webpack, rollup, etc.). It allows you to keep all your env vars in a single .env file which is loaded automatically once you import dotenv into your application.

dotenv also respects your commandline env vars which then take precedence over env vars from your .env file by default. It goes nicely hand in hand with cross-env so I recommend using them together to add some more maintainability to your setup.

The Processes

There are tools on the one side but there are also processes on the other side. Tools can help you get your processes right, support you to keep your codebase clean and tidy but for certain things you need to establish certain processes where tools are limited or not suitable.

Document what you are doing, and how, and why it was done the way it was

Something most developers don’t like to do is to write documentation. I know it’s hard sometimes to write things down instead of writing code but having a good documentation is so important, especially if you’re having a high fluctuation and you’re off- and onboarding new team members regularly. And a good documentation doesn’t have to be the size of a whole book. You can start with a simple README.md in your repository.

Setup a project as if you were new to your own team, clone the repo, install all dependencies, gather all the necessary environment variables and put it in your .env file. Write down every single step. Don’t forget the obivous things you have done a long time ago: installing Node/nvm. Installing helpful editor plugins such as Prettier or ESLint. Provide links for all that and try to think of it as if you were onboarding a Junior Developer to your team.

Then write down all links to your develop, staging and production environment. Give hints where pull requests are deployed to (if they are) and where to find the link to your CI. I guarantee you it probably won’t even take an hour but will in return save you hours of work in the future, whenever you are onboarding new people or setting up the project from scratch. Encourage your colleagues to fix things if they are outdated.

This way they could even create their first Pull Request which is always a good feeling. Creating a Pull Request on your first day in a new project always feels rewarding, even if the only thing you actually fix is a typo or a broken link but it gives you the strong feeling that now, after your first PR, you’re really a member of the team already.

If you’re building installable packages (e.g. via npm) writing a changelog is also a great idea usually. And sometimes also a “decisions” document can be useful. Use it to note down why you have done certain things the way you’ve done it. It can give future team members valuable hints.

Development workflow

Ideally your main branches (usually master and/or develop and sometimes also stage/staging) are protected and nobody in your team has the access rights to directly push code to one of these branches. All work should be done on branches! In my opinion it does not really matter that much if you’re working on feature branches or developer branches or if you’re strictly following Gitflow or not but more important is that you should really never have any of your developers directly push into one of the main branches!

The goal is to make sure that every single change has been peer reviewed and approved by at least one other member of your dev team. All large Git services (GitHub, Gitlab, Bitbucket) have such a feature. This is an easy way to make sure that at least the most obvious bugs can get caught before they are deployed. It also splits responsibility from a single person to at least two persons — the original creator of the PR and the reviewer.

Doing it that way also makes sure that code can be understood by others. If some parts of the code are not understood easily by other members of your team who review your branch you should think about either simplifying it and since that is not always easily possible at least add some comments there to have some inline documentation of what is going on there.

Keep your Pull Requests small. They are easier to review. They are easier to revert. And they are easier to fix if a bug is discovered while in review.

And probably most important: encourage your team members to have a good review culture! Take it serious and don’t underestimate the value of a thorough code review. I have had a project where I spend an hour or even longer on an average work day in code reviews and I have never before seen such a high quality code base.

What is the value of a high quality code base? Developer satisfaction, retention and in the long run: you gain speed by understanding what has been done months ago while at the same time not having to waste hours of fixing bugs every day only because you were careless 3 months ago, just to save 20 minutes of your time. Of course code reviews alone don’t make your code bug free or better maintainable per se but from my experience I can say the more priority the review process had in a team, the less technical debt had been accumulated over time.

This, in turn usually makes your developers happy since nobody likes smelly code and that automatically makes your developers want to write clean code to keep standards high.

Keep your dependencies up to date

There is nothing worse than discovering a bug in a new version of a browser or a device and not being able to fix it because some of your old dependencies are incompatible to other dependencies from your dependency tree which are needed to get this bug fixed. Been there. Done that. Spent almost a week only to update the dependencies in a project that hadn’t gotten any love for almost one and a half years.

During that time a new iPhone and a new iOS was released and for some weird reason my client’s site didn’t work properly anymore. The source for this bug was deep down in the dependency tree and required an update of one of the project’s core dependencies which itself required a new jQuery version etc. etc. etc. Long story short: it was a pain.

So even if you’re only in “maintenance mode” with your product you should at least spend some effort to update your depenencies regularly. At least, say, every 2 months. You should spend even more time to update your dependencies if you’re still actively developing your product. If you do that regularly, at least monthly, it is usually done within half an hour. Given that you have tests for the most important parts of your application of course. In npm you can run npm outdated to see which of your dependencies are outdated, in yarn you can even update them easily by running yarn upgrade-interactive in your terminal.

Conclusion

There are many ways to increase the quality of your codebase, the happiness of your developers and the overall performance of your company. Some of them require a little change in the mindset of the people involved, some of them can be implemented in a few minutes and have massive impact on the success of your team, your product and your company.

In this text I tried to illustrate some of the things you can usually implement pretty quickly and without too much resistance. I encourage you to try that. Not everything that works great in one team works equally well in another team. The things I described are mostly considered “best practice” though, so they should work at least for most of the teams.

Give it a try! And tell me if you did and it worked for you and your team!