Get startedGet started for free

Just one comment

1. Just one comment

Commenting code should be easy. We just write down what is happening in a concise, simple manner. It turns out that nothing is ever easy.

2. I don't know about you...

I don't know about you, but code that I wrote is blatantly obvious to me today. In a few weeks time, it is completely unclear and I'm cursing the person who wrote it.

3. Comments

You can add a comment in R using the hash symbol. Everything after the hash symbol is ignored by R.

4. Tip 1: Avoid obvious comments

My first tip, is to avoid obvious comments. Now what is obvious is clearly subjective. For example, consider these code comments: "Loop through data sets", "Read in data set". With a little experience, they are redundant as the code is sufficiently obvious.

5. Tip 2: Avoid comments that you will never update

My second tip, is to avoid comments that you will never update because you can't be bothered. The most common example I see are comments on the top of the file. These sorts of comments are often neglected. I once saw the comment - list of packages used. This was hopelessly out of date.

6. Tip 3: Be consistent

My third tip is a bit more mundane. Just be consistent. For example, always start a comment with a single hash or double hash. Choose one version and stick with it. Follow rules of grammar. Start with a capital By very careful of jokes. Especially anything that could cause offense. If you have code that looks wrong or is doing something in a non-standard way, be sure to explain yourself. Finally, I find it helpful to note possible future improvements via TODO. Using a standard phrase, means it's easy to search for.

7. Let's practice

OK enough of me, let's practice!