How many comments do you have in your code? Cleaning up nasty code to make easier to follow (CC044)

If you read code you wrote a year ago, what are the odds that you will be able to descipher what you were trying to do? In today's episode Pat demonstrates how he desciphers old smelly code and talks about commenting practices that can help to avoid these problems. How many comments should an R script contain? What makes for a good variable or function name? Watch today's episode to find out. This episode is part of a larger arc of episodes investigating the sensitivity and specificity of amplicon sequence variants (ASVs), also known as exact sequence variants (ESVs). ASVs are growing in popularity for analyzing microbial communities using 16S rRNA gene sequences. Pat demonstrates these concepts by live coding at the command line interface using RStudio, GitHub Flow, and make.

0:00 Introduction
4:05 Getting set up
9:30 Commenting a block of code
31:31 Rendering the markdown document
33:36 Closing the issue
35:15 Conclusion

[drjzee]

More excellent advice. In my experience, the 'why' I am doing something is the critical thing for documentation. The 'how' can be figured out from the code but why I did it followed by how I interpreted the results for the next part of the analysis/manuscript is a huge help down the road for future me. For me, it has also one of the big advantages of using R/reproducible research approaches over the older/other methods of analyzing data (e.g. Excel, GraphPad etc etc.) - allowing me to figure out what is going on and why I did what I did.