In DataS-DHSC/coding_principles_book: Does not matter.

Comment Effectively {#comments}

(ref:comments-intro)

You Must - (ref:comments-must)

You Should - (ref:comments-should)

You Could - (ref:comments-could)

|Related Areas: | Documentation
Easy to Read Code | |--------------- |------------------------------------------------------------|

Comment Style

Use comments judiciously and look to your style guide for advice on how to comment.

What to Capture

Ask yourself: “will I understand this code in a years time?”

Comments should bridge the gap between the documentation and the code. They should be written in plain English and describe the logic and purpose of each chunk of code; i.e. where it fits in and why its there.

What not to Capture

You don't need to describe everything you are doing with the code in a comment. Someone reading the code should be literate in the language. Commenting extensively line by line makes it likely that code and comments will get out of sync when you go back and make changes.

There should be separate documentation for high level questions such as the structure or logic of the analysis. Don't write your plan or QA notes in the comments.

Don't store large chunks of alternate code in the comments. Leave that to your version control system.

Alternatives

If you find yourself writing extensive comments, or writing more comments than code, consider changing format. There are options such as Jupyter Notebooks, and Rmarkdown for combining analysis and prose.

DataS-DHSC/coding_principles_book documentation built on March 11, 2020, 4:13 a.m.