From 0ecc09f6cfb46e79374a3f7329e7f60b9c7b655e Mon Sep 17 00:00:00 2001 From: Aleksandr Hovhannisyan Date: Mon, 24 Jun 2019 08:06:57 -0400 Subject: [PATCH] Clarify wording in comments section --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2227916..12fb993 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ First things first: I want to address the topic of comments. Unnecessary comment In Go, according to `gofmt`, all public variables and functions should be annotated. I think this is absolutely fine, as it gives us consistent rules for documenting our code. However, I always want to distinguish between comments that enable auto-generated documentation and all other comments. Annotation comments, for documentation, should be written like documentation—they should be at a high level of abstraction and concern the logical implementation of the code as little as possible. -I say this because there are other ways to explain code and ensure that the code is being written comprehensibly and expressively. If the code is neither of those, some people find it acceptable to introduce a comment explaining the convoluted logic. The matter of the fact is that most people will not read comments because they're very intrusive to the experience of reading code. +I say this because there are other ways to explain code and ensure that it's being written comprehensibly and expressively. If the code is neither of those, some people find it acceptable to introduce a comment explaining the convoluted logic. Most people simply won't read comments because they tend to be very intrusive to the experience of reviewing code. Let's take a step back and look at some concrete examples. Here's how you shouldn't comment your code: