jeena/en.javascript.info
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge pull request #378 from brentguf/comments

Browse source 
Comments
This commit is contained in:
Ilya Kantor 2018-03-03 09:34:56 +03:00 • committed by GitHub
commit 471de2ed33
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 5 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

8
1-js/03-code-quality/03-comments/article.md
View file

@ -18,7 +18,7 @@ complex;
code;
```
But in a good code the amount of such "explanatory" comments should be minimal. Seriously, a code should be easy to understand without them.
But in good code the amount of such "explanatory" comments should be minimal. Seriously, code should be easy to understand without them.
There's a great rule about that: "if the code is so unclear that it requires a comment, then maybe it should be rewritten instead".
@ -113,7 +113,7 @@ function addJuice(container) {
Once again, functions themselves tell what's going on. There's nothing to comment. And also the code structure is better when split. It's clear what every function does, what it takes and what it returns.
In reality, we can't totally evade "explanatory" comments. There are complex algorithms. And there are smart "tweaks" for purposes of optimization. But generally we should try to keep the code simple and self-descriptive.
In reality, we can't totally avoid "explanatory" comments. There are complex algorithms. And there are smart "tweaks" for purposes of optimization. But generally we should try to keep the code simple and self-descriptive.
## Good comments
@ -158,7 +158,7 @@ Why is the task solved this way?
Comments that explain the solution are very important. They help to continue development the right way.
Any subtle features of the code? Where they are used?
: If the code has anything subtle and counter-obvious, it's definitely worth commenting.
: If the code has anything subtle and counter-intuitive, it's definitely worth commenting.
## Summary
@ -172,7 +172,7 @@ Good comments allow us to maintain the code well, come back to it after a delay
- Function usage.
- Important solutions, especially when not immediately obvious.
**Evade comments:**
**Avoid comments:**
- That tell "how code works" and "what it does".
- Put them only if it's impossible to make the code so simple and self-descriptive that it doesn't require those.