The way to Write Good Code Documentation


Think about a constructing that’s superbly constructed, visually interesting, and structurally sound. The architect needs to be proud, proper? Now think about, over time, components of the constructing erode and wish repairs. No drawback, that occurs. Besides the architect’s designs are nowhere to be discovered. There isn’t a blueprint, no layouts, and no technique to know the place important components of the construction are situated.

You’ll be able to see the issue right here, after all. The identical concern can come up in terms of code. Think about making an attempt to determine what has damaged behind the scenes on a mission that was written years in the past. You may not be aware of the thought strategy of the programmer who wrote it. Heck, it would even be one thing that you simply constructed, however years later, you don’t bear in mind each step of your individual course of.

Code documentation is a course of that helps to mitigate these considerations. In the event you’re simply getting began within the area, chances are you’ll not take into consideration documenting your course of, nevertheless it’s practically as vital because the code itself. Beneath, you’ll discover suggestions for writing documentation that may enable you to file your course of and keep away from widespread errors alongside the best way.

Hold detailed (and correct!) notes

Have you ever ever run right into a recipe that has a time period you aren’t accustomed to, or skips a step as a result of the one that wrote it assumed house cooks would perceive what to do? It may be irritating for anybody following alongside to run into incomplete documentation. That’s why it’s vital to completely doc your course of as you code in order that it may be recreated and maintained if wanted.

Study one thing new without cost

It’s additionally a superb reminder that your course of will not be the identical as another person’s. Whereas the outcomes could also be related in motion, the code behind the scenes could also be written in a method that is sensible to you however wouldn’t to another person. Particulars are essential, each for others studying your documentation and for your self whenever you return and take a look at your work.

Some examples of particulars that it would be best to embrace in your documentation:

  • Terminal instructions
  • Code snippets that you simply copied, and the place you bought them from
  • The order by which you wrote elements of the code

Clarify your choices

There may be a couple of technique to crack an egg even when the outcome is identical. For that motive, it’s vital to clarify why you selected the strategy that you simply did. That is very true if you happen to made an unlikely or shocking alternative. Take into consideration who’ll be studying your code and anticipate the questions that they may ask. Or use the favored “rubber duck” method and take a look at describing your course of or software aloud to an inanimate object.

Generally there could also be a extra standard method, however you select to jot down your code a selected method due to the character of the mission or the result that you’re after. These are vital particulars to doc, with explanations as to why you made the selection that you simply did. To not point out, you’re typically requested to discuss by your method to an issue or mission throughout technical interviews, so it’s a good suggestion to get into the apply of writing it out in your documentation.

At all times embrace a README

Top-of-the-line instruments for code documentation which you could embrace in your mission is a README file. In the event you’re not accustomed to a README, it’s a easy textual content doc that introduces fundamental details about your mission. Anybody concerned within the programming of a mission ought to embrace or contribute to a README, and it’s best to retailer it within the top-level listing of the mission so it may be simply discovered and accessed.

Right here’s an instance of the README for Codecademy Docs, our open-contribution documentation for fashionable programming languages and frameworks.

There are a few components that make for a superb README that you simply’ll need to embrace:

  • An outline of the mission
  • Directions on how you can set up or begin this system
  • A tutorial or instance of how you can use this system

You should use Markdown or any easy textual content editor to create a README. Usually, these recordsdata might be saved as plaintext or reStructuredText.

Use constant naming conventions

While you’re going by the method of documenting your programming mission, you’ll end up labeling and naming recordsdata repeatedly and referencing these recordsdata. One technique to hold issues easy for your self and straightforward to comply with alongside is to have a easy naming conference which you could replicate and simply learn. 

In the event you’re utilizing dates, guarantee that your documentation is ISO 8601 Commonplace, which is an  worldwide normal overlaying the change of date and time-related information. That is the right format to make use of: YYYYMMDDThhmmss (Quick for Yr, Month, Day, Time, Hours, Minutes, Seconds.)

For different recordsdata, you need to set up one thing constant that makes your recordsdata simple to seek out. Take into account together with particulars like:

  • Mission identify
  • The identify or initials of the one that labored on the file
  • The date when the file was created
  • The model variety of the mission that you’re engaged on

Follow makes good

The easiest way to discover ways to produce helpful code documentation is to get some apply in. Share your documentation with others and see if they’ll get your mission working and perceive the way it capabilities based mostly on what you present. 

If you wish to get some reps in studying and contributing to code documentation, Codecademy Docs is a superb place to start out. The community-led effort to supply code documentation for fashionable programming languages and frameworks presents a fantastic alternative to not solely be taught finest practices however to get some apply of your individual.


Leave a Comment