19 Writing comments
Written by Isaac Ehrlich and last updated on 7 October 2021.
19.1 Introduction
In this lesson, you will learn what a comment is, as well as how and when to write them.
19.3 Preamble
Beyond commenting within your code, you may also want to begin each R script with a multi-line comment that provides general information about the contents of the script, also known as a preamble. This preamble may contain information such as the author, date, and purpose of the script.
### Example Preamble ###
# Author: Your Name
# Date: The Date
# Contact: Your Email
# Prerequisites: Necessary Data of Folder Set-Up
# Links or Resources
# Purpose19.5 Key takeaways
- Comments are an invaluable way to organize code and improve readability
- Comments are an effective way of explaining code and the decisions made when writing
- Comments help the author just as much as they help other readers!
- Simple commands and lines do not require comments, but make sure to always comment thoroughly where necessary!
19.2 Comments
19.2.1 Why comment?
When revisiting code you have previously written or when reviewing someone else’s code, it is not always immediately clear what the code is doing or how it is working - especially if it is not commented. This makes code difficult to interpret, and hard to edit. By adding comments and explaining what is happening in the code, you make it easier to decipher and understand for when you inevitably return to it in the future.
19.2.2 How to comment?
In R, comments are written by adding a
#before text, typically at the beginning of the line. This means that anything written after the#will not be interpreted as code by R, but rather as text. Comments also typically precede the code they are referring to.If you want to comment more than one line of code, you can select the desired lines and then use the shortcut “ctrl + shift + C” (or “cmd + shift + C” on Mac).
19.2.3 When to comment?
Comments are typically used to improve the readability of code, either by partitioning code into sections, explaining the code, or providing links to additional resources. Not every line of code needs a corresponding comment, it is up to you to determine when you should write a comment. There are certain instances however that typically benefit from commenting.
You can use comments to divide sections of your analysis. Often, you can split a single script into multiple sections, such as setting up the environment, writing functions, and sections of your analysis.
When you write new functions, its common practice to explain the inputs, output, and purpose of each function
While performing operations such as addition or subtraction typically won’t require commenting, once your code begins to involve complex chunks and functions, it becomes important to explain what is going on so that you don’t need to figure it out again in the future.
When performing analyses, you may make decisions based on reasoning that is not always evident. In these situations, it is helpful to include a comment explaining the decision you’ve made. If your code or reasoning also refers to some external source, it may be helpful to provide a link to the source.