Recently, as I looked at some of my old projects, I was stunned at the amount of both Javascript and PHP dependencies I had. I remembered a few of their purposes, but for others, I was left in the dark as to why I included them initially. Returning to projects became quite a nightmare because I couldn’t remember why some dependencies were there and others were not.
I can’t predict the future of any dependency and neither can you, but I made a change to help supplement my project’s organization and, since, it has helped greatly.
Whether your project is internal, private or public, a readme file in the root of the project will always help. I tend to list the project language, framework and a quick install guide. This is more or less for anyone who takes on the project in the future. This gives them the exact steps they’ll need to spin up my project on their own.
These steps don’t have to be as precise as measurements in a laboratory, but, you should, at the least, leverage links when needed. For example, the first instruction in one of my projects is to, “Get Composer” — with a hyperlink to the Composer homepage.
Copying install instructions for dependencies is difficult because they might change between versions and platforms, so I leave that to the respective website itself. Anyone encountering this readme will be able to follow that link and install the dependency from those instructions.
Additionally, I like listing every 3rd party dependency I use in the readme. This is a simple bullet list with the name of the dependency, the website to said dependency and a few quick words about it.
For example:
image.intervention.io – Intervention – Used for automating creation of thumbnails for users.
This immediately tells me the name of the dependency, the website for more information and how it’s connected to my project. Every time I add a dependency, one of my first code changes is to the readme with an added line modeled like the above example. Contributors, reviewers and others will instantly know why the dependency was added and can easily review it.
These few tips helped me greatly organize my projects. As the amount of projects you work on grows, the ability to remember all of them becomes unrealistic. Not to mention co-workers, contributors and reviewers will thank you as well.
