Mark Niemann-Ross says the rest is commentary:
If you are reading this, you’re a coder and use functions. We write them for ourselves. If someone else writes a function, you can hope it works. If it doesn’t, you can hope to fix it. Hopefully, the return value is obviously correct. But maybe it’s subtly wrong?
If things are amiss, read the name of the function and hope it’s descriptive. I worked with a programmer who omitted all vowels from his function names. So the above code would expand to this…
Read on for the rationale behind commenting your functions appropriately, as well as one way to do it in R. There is a bit of art and a bit of science to writing good comments, but the starting point is simply having them to begin with. And the more clever you feel like you’re being, the more you need to comment this, because three months from now, you probably won’t be feeling quite as clever. H/T R-Bloggers.