Imagine a building that’s beautifully constructed, visually appealing, and structurally sound. The architect should be proud, right? Now imagine, over time, parts of the building erode and need repairs. No problem, that happens. Except the architect’s designs are nowhere to be found. There is no blueprint, no layouts, and no way to know where essential parts of the structure are located.
You can see the problem here, of course. The same issue can arise when it comes to code. Imagine trying to figure out what has broken behind the scenes on a project that was written years ago. You might not be privy to the thought process of the programmer who wrote it. Heck, it might even be something that you built, but years later, you don’t remember every step of your own process.
Code documentation is a process that helps to mitigate these concerns. If you’re just getting started in the field, you may not think about documenting your process, but it’s nearly as important as the code itself. Below, you’ll find tips for writing documentation that will help you record your process and avoid common mistakes along the way.
Keep detailed (and accurate!) notes
Have you ever run into a recipe that has a term you aren’t familiar with, or skips a step because the person who wrote it assumed home cooks would understand what to do? It can be frustrating for anyone following along to run into incomplete documentation. That’s why it’s important to fully document your process as you code so that it can be recreated and maintained if needed.
Learn something new for free
It’s also a good reminder that your process may not be the same as someone else’s. While the outcomes may be similar in action, the code behind the scenes may be written in a way that makes sense to you but wouldn’t to someone else. Details are crucial, both for others reading your documentation and for yourself when you go back and look at your work.
Some examples of details that you will want to include in your documentation:
- Terminal commands
- Code snippets that you copied, and where you got them from
- The order in which you wrote aspects of the code
Explain your decisions
There is more than one way to crack an egg even if the result is the same. For that reason, it’s important to explain why you chose the method that you did. This is especially true if you made an unlikely or surprising choice. Think about who’ll be reading your code and anticipate the questions that they might ask. Or use the popular “rubber duck” technique and try describing your process or tool aloud to an inanimate object.
Sometimes there may be a more conventional approach, but you choose to write your code a specific way because of the nature of the project or the outcome that you are after. These are important details to document, with explanations as to why you made the choice that you did. Not to mention, you’re often asked to talk through your approach to a problem or project during technical interviews, so it’s a good idea to get into the practice of writing it out in your documentation.
Always include a README
One of the best tools for code documentation that you can include in your project is a README file. If you’re not familiar with a README, it’s a simple text document that introduces basic information about your project. Anyone involved in the programming of a project should include or contribute to a README, and you should store it in the top-level directory of the project so it can be easily found and accessed.
Here’s an example of the README for Codecademy Docs, our open-contribution documentation for popular programming languages and frameworks.
There are a couple of elements that make for a good README that you’ll want to include:
- A description of the project
- Instructions on how to install or start the program
- A tutorial or example of how to use the program
You can use Markdown or any simple text editor to create a README. Typically, these files will be saved as plaintext or reStructuredText.
Use consistent naming conventions
When you’re going through the process of documenting your programming project, you’ll find yourself labeling and naming files regularly and referencing those files. One way to keep things simple for yourself and easy to follow along is to have a simple naming convention that you can replicate and easily read.
If you’re using dates, make sure that your documentation is ISO 8601 Standard, which is an international standard covering the exchange of date and time-related data. This is the correct format to use: YYYYMMDDThhmmss (Short for Year, Month, Day, Time, Hours, Minutes, Seconds.)
For other files, you want to establish something consistent that makes your files easy to find. Consider including details like:
- Project name
- The name or initials of the person who worked on the file
- The date when the file was created
- The version number of the project that you are working on
Practice makes perfect
The best way to learn how to produce useful code documentation is to get some practice in. Share your documentation with others and see if they can get your project working and understand how it functions based on what you provide.
If you want to get some reps in reading and contributing to code documentation, Codecademy Docs is a great place to start. The community-led effort to provide code documentation for popular programming languages and frameworks offers a great opportunity to not only learn best practices but to get some practice of your own.
Subscribe for news, tips, and more
