0%

Header and comment template in R script

记录几个生成R脚本的header及注释的方法

在编写脚本过程中加上注释是必不可少的步骤,不仅方便自己也方便他人,有时这个是工作中必须的一步。。。

个人常用的方式是#-(破折号)的组合,有时为了简单,就手动打一个#号,然后依次N个-(破折号);但假如为了整体代码的美观,可能会刻意保持统一的破折号个数,这时难道要每次都数一下破折号的个数么?

Rstudio给了一个比较快捷的方式,如输入Ctrl + Shift + R,然后输入注释内容,即可产生一行注释header,结合Rstudio的Top level功能可随时定位到每条注释header位置

# This is the first comments header ---------------------------------------

这样就不用刻意数破折号的个数啦,每次都是统一的格式


假如觉得注释行或者注释块不够的好看,或者说想加入更多的内容,则可以考虑试下bannerCommenter包,大致上有bannerblockboxupopen_box等函数可供使用

个人比较喜欢用的是banner,如:

> bannerCommenter::banner("This is the first comments header", centre = TRUE, bandChar = "-")

##---------------------------------------------------------------
##              This is the first comments header              --
##---------------------------------------------------------------

虽然这个comment是显示在console window中的,但是其实该comment已经保存在系统复制管道中了,只是在script中输入Ctrl+v黏贴即可呈现出来


假如想给项目的代码中加入一些固定的项目信息,比如项目名称、作者、时间、描述等信息,那么比较合适的方法是在script中添加一个header;比如一些包的加载,全局变量以及固定的脚本,都可写在script的header中

有人整理了一些关键的信息,如:

  • Script name: I try to use descriptive names. Something like summarising_soil_hazards.R is almost always going to be better than an uniformative name like script1.R….
  • Purpose of the script: Just writing this down often helps clarify what exactly I am trying to do.
  • Author(s): I share many of my scripts with my students, colleagues and clients – it is good to know where the script originated if they have any questions, comments or wish to suggest improvements
  • Date Created: This date is automatically filled in with my template script. (Some people also like to include an updated field, but I tend to forget to fill this in and would rather get this data from version control)
  • Copyright statement / Usage Restrictions: For intellectual property (IP) reasons it is good to know where the copyright resides, and how you are happy for people to use your work. You may wish to use a formal type of licence.
  • Contact Information: It helps if people know who to contact, and how they can reach you the best. It’s not uncommon for me to include both my personal and work email accounts. I do this in case one of them ceases to be in service in the future for whatever reason.
  • Notes: This is a free-text space which I use to jot down any thoughts or more detailed notes about the script, or even work to do.

以上参考自:My easy R script header template

有时候我们比较简单的方法就是在网上找一下别人的header模板,然后修改至满足自己个性化的需求后,保存在自己电脑的本地,等需要的再copy/paste出来

Rstudio提供了一个更加方便的工具:snippets

点击Rstudio的Tools -> Global Options -> Code -> Tab Editing -> Snippets -> "Edit Snippets" ,然后拉到最下面,输入下面的template(具体内容可个性化的修改):

snippet template_header
    ## ---------------------------
    ##
    ## Script name: 
    ##
    ## Purpose of script:
    ##
    ## Author: Dr. Timothy Farewell
    ##
    ## Date Created: `r paste(Sys.Date())`
    ##
    ## Copyright (c) Timothy Farewell, `r paste(format(Sys.Date(), "%Y"))`
    ## Email: hello@timfarewell.co.uk
    ##
    ## ---------------------------
    ##
    ## Notes:
    ##   
    ##
    ## ---------------------------
    
    ## set working directory for Mac and PC
    
    setwd("~/Google Drive/")        # Tim's working directory (mac)
    setwd("C:/Users/tim/Google Drive/")     # Tim's working directory (PC)
    
    ## ---------------------------
    
    options(scipen = 6, digits = 4) # I prefer to view outputs in non-scientific notation
    memory.limit(30000000)      # this is needed on some PCs to increase memory allowance, but has no impact on macs.
    
    ## ---------------------------
    
    ## load up the packages we will need:  (uncomment as required)
    
    require(tidyverse)
    require(data.table)
    # source("functions/packages.R")       # loads up all the packages we need
    
    ## ---------------------------
    
    ## load up our functions into memory
    
    # source("functions/summarise_data.R") 
    
    ## ---------------------------

保存后,若想调用,就在script中输入template_header,然后tab键即可调用了

个人觉得很好用哈。。。


参考资料:

https://bookdown.org/yih_huynh/Guide-to-R-Book/r-conventions.html
bannerCommenter
My easy R script header template

本文出自于http://www.bioinfo-scrounger.com转载请注明出处