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!

Create Your Free Account

By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.