Thread by @neilgcurrie

A pillar of good coding is good documentation. And it goes beyond just comments.

How to write great documentation for your code in R.

#rstats #coding #datascience

Documenting your code is essential so that others, or future you, can understand what is going on.

Coding is complicated. What is obvious to you may not be obvious to someone else. Good documentation can help them out.

The first thing we will look at are comments.

1/18

In R, one of the first things you probably learned was writing a comment with a hashtag #

When writing comments focus on the why - for instance, giving some business context is more useful than explaining what is going on in a simple calculation.

2/18

If something is complicated though, don't be afraid to explain the how. Over-documenting isn't ideal but I'd argue it's better to overdo it than under do it.

Documentation is not just comments though.

Well named objects and functions will improve understanding.

3/18

In the attached example, I find the one without comments is easier to interpret.

4/18

Documentation goes beyond just well written code and comments though.

How we choose to organise our work can improve documentation.

This is where packages and roxygen2 come in.

5/18

Last week I wrote a thread about how to write your own analysis package.

If you aren't familiar with package building, give it a read first.

A benefit of organising your projects in packages is they make creating great documentation easy.

Especially if you use roxygen2.

6/18

https://twitter.com/neilgcurrie/status/1572254358397681665

The roxygen2 package lets you write function documentation, with great syntax, right next to your function code.

It then processes this, automatically creating everything needed to generate professional help files.

7/18

roxygen2 comments start with #'.

We can use keywords with the @ symbol to create the rest of the documentation.

Twitter isn't great for describing this since using @ will mention accounts so read on for attached examples which add some clarity.

8/18

To add a title or description use the title and description keywords respectively.

In fact, for these parts you don't even need the keywords, the first sentence will default to the title and the second paragraph will default to the description.

9/18

To add arguments use the param keyword followed by the name of the argument and your description.

Just separate everything with a space.

You can combine arguments into one, separating them with a comma.

10/18

Information on outputs can be added with the returns and details keywords.

Under returns, typically you detail the shape of the output.

Under details this may be a longer paragraph discussing more details about the function and the output.

11/18

Always add a worked example using the examples keyword.

Reading worked examples is a great way to improve understanding. So these are important.

Finally use the export keyword to make sure the documentation gets processed.

12/18

Putting it altogether you will have something like the attached.

13/18

To create the documentation run:

devtools::document()

To load (or reload) your package run:

devtools::load_all()

Now you can use ?myfunction to read the help files for that function - the same as pro packages like ggplot2 or lubridate.

14/18

With packages and projects you can also add a README file.

README files are written using markdown syntax for styling your text and creating things like tables or bulleted lists.

Just create a README .md file in your project directory.

15/18

As an example, my threads Github repo has a README file which you can find here if you scroll down:

github.com/neilcuz/threads

This is generated by this underlying code here:

raw.githubusercontent.com/neilcuz/thread…

Written all inside R.

16/18

To recap:

Good documentation is essential for great code.

In comments, focus on the why, using great naming to improve readability.

Organise code in packages and document with roxygen2 to create pro help files easily.

Do your readers a favour and add a README file.

17/18

Thanks for reading, if you liked this thread follow me @neilgcurrie for mainly R and data tweets.

Code for this one is here:

github.com/neilcuz/thread…

Code and links to my other threads can be found here:

github.com/neilcuz/thread…

18/18

https://twitter.com/neilgcurrie/status/1574791025310121985