Makefiles As Executable Documentation

As software developers, we often find ourselves working on multiple codebases, constantly hopping between programming languages and frameworks. Keeping track of all the commands and configurations for each project can be a mild annoyance. This is where the humble Makefile shines as a task runner documenting the most essential commands in a project.

Let's take this website's Makefile as an example:

.PHONY: fix dev lint

	npx prettier --write .

	npx remix dev

	npx tsc
	npx eslint app
	npx prettier --check .

Now, this is a very simple Makefile, and lots of real world projects will have more complex ones, but the point still stands: When you revisit a project after an extended hiatus, a glance at the Makefile is often all you need to get back on track. The Makefile becomes a time capsule that encapsulates the project's critical commands and intentions.