FIXME's or do your TODO's ever again!
Photo by Dominik Krzemiński, Developer of TODOr
TODOr Is an incredibly helpful R Package and RStudio Add in that makes the management of all of your developer comments incredibly easy.
What can TODOr do for you?
How often does this happen to you:
“I need to remember to fix this bug…”
mean[1] # FIXME: This doesn't work
#> Error in mean[1] : object of type 'closure' is not subsettableThen you move on and continue your work intending to come back to this issue later. A codebase could be littered with these types of comments. These Reminders that R Package developers create with every intention of correcting, can often be forgotten or misplaced within a sprawling codebase.
TODOr eases the burden of technical debt when it comes to resolving all of these reminders for the health of your codebase.
TODOr will find all of these reminders in an entire file, project, or package. Even multiple types of files are supported and you will be given an itemized list of what type of reminder, the details of the reminder, the file its located in, the line it’s on, and clicking an item in this list will take you exactly to the line of code you needed to fix!
What do you need to do to witness this power? Just this:
todor::todor()
What are the defaults?
By default, TODOr will return all of the comments with the correct markers (i.e. “TODO”, “FIXME”, etc.) in an entire R Project (when you have a .Rproj file in the directory) not just the current file.
“ALL the comments? But i don't care about ALL the comments, only my TODO’s…”
What is returned is not literally every comment, TODOr looks for comments beginning with marker words. The defaults are:
- FIXME
- TODO
- CHANGED
- IDEA
- HACK
- NOTE
- REVIEW
- BUG
- QUESTION
- COMBAK
- TEMP
Beyond the defaults
Search Scope
TODOr can look at more than just a project, you can also have it search a single file:
todor::todor_file("my_file.Rmd")Or even an entire R package:
todor::todor_package()Markers
By default, TODOr will look for all of the aforementioned comment markers. You will get a list of all of them returned to you but what if you have a very large codebase? Like ggplot2 big?
You may want to only look at a few specific types of comments we can do this by passing a vector to the function:
todor::todor(c("TODO", "FIXME"))This will only show the comments that are TODO’s and FIXME’s. So in this way we can filter our searches down to which types of comments we want returned and from specific files.
What if you don't like the default markers?
What if you wanted this functionality for your team but you wanted to tag comments with your team members' names?
We can actually define a custom list of TODOr search patterns so that we can define new keywords for the function to find throughout our codebase. To do this we need to use the options function:
options(todor_patterns = c("FIXME", "TODO", "BRYAN"))Now whenever I place my name next to a comment, it will be picked up by TODOr as a valid marker comment to be returned*.
*It is important to note that these search patterns are case sensitive:
# BRYAN please fix this bug <---- would be picked up
# bryan please fix this bug <---- This would be ignored
TODOr can look beyond just .R files
There are a variety of options we can control in TODOr
There are several other file types that TODOr can find markers in and return in a list format. To make it so these other file types will be searched we can configure some of these options with the options() function.
todor_rmd — When set to TRUE it searches also through Rmd(Rmarkdown) files (default TRUE).
The Rmarkdown marker comments returned will be both code chunk and markdown space comments that use HTML syntax:
Rmarkdown Comments
todor_rnw — When set to TRUE it searches also through Rnw(Sweave) files (default FALSE).
Sweave is the combination of LaTeX with executable R code chunks, the comments that will be returned are both the code chunk and LaTeX comments:
Sweave Document
Sweave Comments
todor_rhtml — When set to TRUE it searches also through RHTML files (default FALSE).
Just like RMarkdown documents both the HTML style and R style comments will be picked up as long as the correct marker is used.
RHTML Document
RHTML Comments
todor_exlude_packrat — When set to FALSE, all files in the “packrat” directory are excluded (default TRUE).
If you have ever used packrat to take a snapshot of your package or project dependencies for reproducibility, then you probably don't want TODOr to pick up all the developer comments for all of those dependency packages.
I ran this once and you definitely want to change this to FALSE as the default is TRUE and you may get a list like this:
Endless Developer Comments
Packrat Option set to FALSE
What if you actually wanted to ignore R files? This option only ignore R script files not RMarkdown.
todor_exclude_r — When TRUE, it ignores R files (default FALSE)
Overall the options() you can use with TODOr:
In Summary
I hope you found this article helpful and decide to use TODOr in your workflow. I have used this package in production with my work in the public sector government and found it to be incredibly helpful to pepper in comments to myself and then easily follow up on them later.
If you prefer a video format of this package review and want to grab all the files i use in my R Package reviews you can get them here:
For all of my R Package reviews I also keep all code and sample documents available in a single repo if you would like any of the code/documents I used in the making of this review:
If you enjoy R Package reviews you can check out my previous review on the Patchwork package:
