Collective Wisdom from the Experts 137
When you set up your project, don’t be stingy: place all the project’s assets
under version control. In addition to the source code, include the documenta-
tion, tools, build scripts, test cases, artwork, and even libraries. With the com-
plete project safely tucked into the (regularly backed up) repository, the potential
damage of losing your disk or data is minimized. Setting up for development
on a new machine involves simply checking out the project from the reposi-
tory. This simplifies distributing, building, and testing the code on different
platforms: on each machine, a single update command will ensure that the
software is the current version.
Once you’ve seen the beauty of working with a version control system, follow-
ing a couple of rules will make you and your team even more effective:
- Commit each logical change in a separate operation. Lumping many changes
together in a single commit will make it difficult to disentangle them in the
feature. This is especially important when you make project-wide refactor-
ings or style changes, which can easily obscure other modifications. - Accompany each commit with an explanatory message. At a minimum,
describe succinctly what you’ve changed, but if you also want to record
the change’s rationale, this is the best place to store it. - Finally, avoid committing code that will break a project’s build, otherwise
you’ll become unpopular with the project’s other developers.
Life under a version control system is too good to ruin it with easily avoidable
missteps.