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!