Find out how to Write Good Code Documentation


Think about a constructing that’s superbly constructed, visually interesting, and structurally sound. The architect must be proud, proper? Now think about, over time, components of the constructing erode and want repairs. No downside, that occurs. Besides the architect’s designs are nowhere to be discovered. There isn’t any blueprint, no layouts, and no approach 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 subject can come up in relation to code. Think about making an attempt to determine what has damaged behind the scenes on a undertaking that was written years in the past. You may not be aware about the thought means of the programmer who wrote it. Heck, it would even be one thing that you simply constructed, however years later, you don’t keep in mind each step of your personal course of.

Code documentation is a course of that helps to mitigate these considerations. For those who’re simply getting began within the subject, chances are you’ll not take into consideration documenting your course of, nevertheless it’s almost as necessary because the code itself. Under, you’ll discover suggestions for writing documentation that can allow you to document your course of and keep away from widespread errors alongside the way in which.

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 who 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 necessary to completely doc your course of as you code in order that it may be recreated and maintained if wanted.

Be taught one thing new totally free

It’s additionally reminder that your course of might 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 while you return and take a look at your work.

Some examples of particulars that you’ll want to embrace in your documentation:

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

Clarify your selections

There may be multiple approach to crack an egg even when the end result is identical. For that cause, it’s necessary to clarify why you selected the tactic that you simply did. That is very true for those who 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 instrument aloud to an inanimate object.

Generally there could also be a extra typical method, however you select to write down your code a selected method due to the character of the undertaking or the result that you’re after. These are necessary 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 speak by your method to an issue or undertaking throughout technical interviews, so it’s a good suggestion to get into the apply of writing it out in your documentation.

All the time embrace a README

Probably the greatest instruments for code documentation you could embrace in your undertaking is a README file. For those who’re not accustomed to a README, it’s a easy textual content doc that introduces primary details about your undertaking. Anybody concerned within the programming of a undertaking ought to embrace or contribute to a README, and it’s best to retailer it within the top-level listing of the undertaking so it may be simply discovered and accessed.

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

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

  • An outline of the undertaking
  • Directions on set up or begin this system
  • A tutorial or instance of use this system

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

Use constant naming conventions

If you’re going by the method of documenting your programming undertaking, you’ll end up labeling and naming recordsdata commonly and referencing these recordsdata. One approach to hold issues easy for your self and simple to comply with alongside is to have a easy naming conference you could replicate and simply learn. 

For those who’re utilizing dates, ensure that your documentation is ISO 8601 Customary, which is an  worldwide customary overlaying the trade of date and time-related knowledge. 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 search out. Contemplate together with particulars like:

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

Apply makes good

One of the best ways to learn to produce helpful code documentation is to get some apply in. Share your documentation with others and see if they’ll get your undertaking working and perceive the way it features 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 begin. The community-led effort to offer code documentation for widespread programming languages and frameworks presents a terrific alternative to not solely be taught greatest practices however to get some apply of your personal.


Leave a Comment