Best practices to comment R pipeline %>% [closed]

Question

When writing long pipelines with R and dplyr/tidyr, has anybody found a good way to add comments?

I know that the function syntax is already pretty expressive, but sometimes multiple actions could be "grouped" together and I wonder if it is better to break the whole thing in multiple pipelines with comments between them or if there is a way to nicely format the comments within the pipeline.

Answer 1

Not really an answer, but too long for a comment--

I personally just put my comments in between commands in the pipe. For example:

object %>%
  command1 %>%

  #* Comment

  command2 %>%
  command3 %>%

  #* Perhaps a 
  #* Really long
  #* Comment

  command4

The key, for me, is indenting your comment to the same level as the code it discusses so that I can visualize that it is part of a single block.

Answer 2

Alternatively:

object %>%
  command1 %>%  #* Comment
  command2 %>%
  command3 %>%   #* Perhaps a 
                 #* Really long
                 #* Comment
  command4

Though, to be honest, I think this practice in general is too much commenting and is akin to:

# increment x by 1
x <- x + 1

That is you should assume that whomever is reading your code can evaluate code and should only really use comments for bigger ideas. EG.

# In this section I calculate summaries and cummulative statistics of of X,Y,Z by factors A,B. 
# And then plot them. Note the plots exhibit ...
object %>%
  command1 %>%  
  command2 %>%
  command3 %>%  
  command4

ggplot(...) + geom_bar(...) + facet_grid(...) + theme(...)

If you really need to be doing substantial commenting, your code is probably too complex for interactive use. You should probably put it into a generalizable function and document the function.