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

images to svg

Browse source
This commit is contained in:
Ilya Kantor 2019-07-28 15:42:37 +03:00
parent a31e881856
commit 3ba28aa104
734 changed files with 11682 additions and 245 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -4,7 +4,7 @@ As we know from the chapter <info:structure>, comments can be single-line: start
We normally use them to describe how and why the code works.
At first sight, commenting might be obvious, but novices in programming usually get it wrong.
At first sight, commenting might be obvious, but novices in programming often use them wrongly.
## Bad comments
@ -120,9 +120,9 @@ In reality, we can't totally avoid "explanatory" comments. There are complex alg
So, explanatory comments are usually bad. Which comments are good?
Describe the architecture
: Provide a high-level overview of components, how they interact, what's the control flow in various situations... In short -- the bird's eye view of the code. There's a special diagram language [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) for high-level architecture diagrams. Definitely worth studying.
: Provide a high-level overview of components, how they interact, what's the control flow in various situations... In short -- the bird's eye view of the code. There's a special language [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) to build high-level architecture diagrams explaining the code. Definitely worth studying.
Document a function usage
Document function parameters and usage
: There's a special syntax [JSDoc](http://en.wikipedia.org/wiki/JSDoc) to document a function: usage, parameters, returned value.
For instance: