Code for Lazy People: function to generate headings
Published:
In this Code for Lazy People blog series, I share coding tools that make my daily work more efficient — because, honestly, I prefer to work smarter, not harder. Like many researchers, I often deal with repetitive tasks, and instead of doing them manually, I use code to automate them. Over time, I have built a collection of such tools that help me save time and effort. That’s one of the things I love about coding: once you create a solution, you can recycle it for future projects instead of reinventing the wheel every time.
Code headings
One of such repetitive tasks is to create code section separated by text and visual symbols. For example, say you want to highlight a particular code section where you will prepare your data. You could write something like:
# Data preparation for main analysis A
While this is good enough for short codes, it may be hard to track this section visually once you have a few hundred more lines. In that case, you may write something like:
######################################
# Data preparation for main analysis A
######################################
The additional formatting helps you track visually each section within a code file. Yet, it becomes fairly annoying to manually align everything to ensure that each section is consistent in length and shape.
######################################
# Data preparation for main analysis A
######################################
# ...
############################################
# Data preparation for main analysis B and C
############################################
# ...
##########################################
# Save processed data for further analysis
##########################################
# ...
####################################################################
# Save processed data for further analysis with a fancier encasing #
####################################################################
# ...
The examples above are also good enough for short titles. However, when I am actively writing code, I find it unpractical to always re-write the comment symbol a few times ####, then copy-paste it a few times, and manually align everything.
Naturally, I made a function that automatically does that:
- create code heading with (customizable) symbols;
- auto-align spacing for a given (customizable) length, so that symbols and text are always consistent;
- allows for additional white lines for larger visual delimitation.
- automatically copy the resulting heading so you can
CTRL+Vdirectly in your document after execution.
SAS users: You should use R instead. Just kidding. I also made a SAS version a few years ago. It works similarly and you can download it here.
make_title R function
You can copy and paste the code below, save it in a .R script, and run it before you wish to use it. You can also download the script here.
#' @title Make Titles for Codes
#'
#' @description Generate heading or title as comments to organize R script
#'
#' @param title The text that will be used as the heading
#' @param total_width The total width of the heading, including the symbol characters and spaces. The default is 75.
#' @param left_aligned A logical value indicating whether the title should be left-aligned within the heading (TRUE) or centered (FALSE). The default is FALSE.
#' @param blank_line The number of blank lines to be added before and after the heading. The default is 0.
#' @param symbol The symbol character used to create the heading. The default is <*>.
#'
#' @return An R comment message with the title that is also copied to clipboard.
#'
#' @examples #make_title("Introducing: the <make_title> function",blank_line=1)
#'
#' @importFrom clipr write_clip
#' @export
make_title <- function(title,total_width=75,left_aligned=FALSE,blank_line=0,symbol='*'){
# output n stars, title width + half, n blanks
n_stars <- total_width-2
title_width <- nchar(title)
# Hard stop if title too long
if(title_width > (total_width-5)) {
new_try <- title_width+5
message(paste("ERROR: Current title is too large to fit with a <total_width> of",total_width))
message(paste("Tip: Try a <total_width> of",new_try,"instead"))
stop()
}
title_width_half <- title_width/2
n_blanks <- total_width-4
# find heading center
heading_center <- floor(n_blanks/2)
# calculate blanks to the right and to the left of title
left_blanks <- ifelse(left_aligned==FALSE,heading_center-title_width_half,0)
right_blanks <-
ifelse(left_aligned==FALSE,
ifelse(title_width %% 2 == 0, # +/- 1 depending on even/uneven title length
n_blanks - (left_blanks+title_width)-1,
n_blanks - (left_blanks+title_width))+1,
n_blanks - (left_blanks+title_width))
# make vector of blanks
symbol_vector <- paste0(replicate(n_blanks,symbol),collapse="")
blank_vector <- paste0(replicate(n_blanks," "),collapse="")
left_blanks_vector <- paste0(replicate(left_blanks," "),collapse="")
right_blanks_vector <- paste0(replicate(right_blanks," "),collapse="")
# Create heading
row1 <- paste0('# ',symbol_vector,' #')
row2 <- paste0('# ',left_blanks_vector,title,right_blanks_vector,' #')
row3 <- paste0('# ',symbol_vector,' #')
row0 <- paste0('# ',blank_vector,' #')
# Output heading
message(row1)
if(blank_line>0) message(row0)
message(row2)
if(blank_line>0) message(row0)
message(row3)
# copy to clipboard
if(blank_line>0) {
to_copy <- c(row1,rep(row0,blank_line), row2,rep(row0,blank_line), row3)
clipr::write_clip(to_copy,breaks="\n")
} else {
to_copy <- c(row1,row2,row3)
clipr::write_clip(to_copy,breaks="\n")
} # end of copy to clipboard
}
As you can see, the function is neither very complicated nor fancy. The most “advanced” feature - to automatically transfer the resulting heading to copy/paste - is actually performed using the clipr package. I typically use the function directly in the console and not necessarily in the code file per se. In other words, I don’t track how I generated the titles, since I am only using the resulting text in my codes.
Before we dive in some examples, I want to point out that I found after the fact that an R package for that already existed. I have never used it, but you can check bannerCommenter on Cran.
Example 1: Large heading at the top of a code file
Sometimes it is useful to include a large heading at the top of a code .R code file to describe what it is about. For such code, we will added 2 blank lines using blank_line=2. The actual title does not matter, as long as it fits within the character length specified in total_width, that is, 75 by default.
# Code I would enter in the console to generate a heading for a code file
make_title("Code 01 - Initial data preparation", blank_line=2)
# *********************************************************************** #
# #
# Code 01 - Initial data preparation #
# #
# *********************************************************************** #
A preview is shown in the console, but it will not show all blank lines for tidyness. The actual result that would be pasted in the code file is shown below:
# *********************************************************************** #
# #
# #
# Code 01 - Initial data preparation #
# #
# #
# *********************************************************************** #
Example 2: Small heading at the top of a code section
Next, we may want to separate code section that perform different tasks within a code file.
# Code I would enter in the console to generate a heading for a code section
make_title("Data preparation for data A")
# *********************************************************************** #
# Data preparation for data A #
# *********************************************************************** #
Since we do not have blank lines, the resulting text is consistent with the preview:
# *********************************************************************** #
# Data preparation for data A #
# *********************************************************************** #
We can also reduce the total width for subsections. For example, I can generate a subheading with a total width of 50 characters, total_width=50.
# Code I would enter in the console to generate a subheading for a code section
make_title("Import raw data", 50)
# ********************************************** #
# Import raw data #
# ********************************************** #
Again, the resulting text is consistent with the preview:
# ********************************************** #
# Import raw data #
# ********************************************** #
Example 3: Further customization
There are many ways in which you could customize your headings for different purpose. I present a two options.
# Using a different symbol
make_title("Further customization", symbol="-")
# ----------------------------------------------------------------------- #
# Further customization #
# ----------------------------------------------------------------------- #
# Using a left alignment
make_title("Author: Last name, first name", left_aligned = TRUE)
# *********************************************************************** #
# Author: Last name, first name #
# *********************************************************************** #
Example 4: combination with RStudio’s built-in code sections
RStudio also includes a built-in approach to separate code section using at least four comment symbols ####. I often combine both the RStudio approach and large comment headings to benefit from the advantages of both.
#### First step in my code ####
# *********************************************************************** #
# This is the first step in my code #
# *********************************************************************** #
# ...
##### This is the first substep #####
# ********************************************** #
# This is the first substep #
# ********************************************** #
# ...
Now, I would agree that the combination of both may be a bit overkill. Nonetheless, I do believe it helps me organize longer codes more easily! I think that having a clear outline really helps others to navigate through your code. Or maybe even yourself in a few months/years from now.