x/clean-go-article
1
0
Fork 0
mirror of https://github.com/Pungyeon/clean-go-article.git synced 2024-11-23 14:14:05 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Clarify wording in comments section

Browse source
This commit is contained in:
Aleksandr Hovhannisyan 2019-06-24 08:06:57 -04:00
parent 24e0941a65
commit 0ecc09f6cf
1 changed files with 1 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -60,7 +60,7 @@ First things first: I want to address the topic of comments. Unnecessary comment
In Go, according to `gofmt`, <em>all</em> 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 <em>all other</em> comments. Annotation comments, for documentation, should be written like documentation&mdash;they should be at a high level of abstraction and concern the logical implementation of the code as little as possible. In Go, according to `gofmt`, <em>all</em> 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 <em>all other</em> comments. Annotation comments, for documentation, should be written like documentation&mdash;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 <em>shouldn't</em> comment your code: Let's take a step back and look at some concrete examples. Here's how you <em>shouldn't</em> comment your code: