From 643cc5b0d640a51c526402c1a34e64584dafbfb0 Mon Sep 17 00:00:00 2001 From: yogabonito Date: Tue, 2 Dec 2025 16:42:31 +0100 Subject: [PATCH] [DOC] improve language slightly --- 1-js/03-code-quality/03-comments/article.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index af3a06c80b..6a9daa5acf 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -120,7 +120,7 @@ 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 language [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) to build high-level architecture diagrams explaining the code. 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 called [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) to build high-level architecture diagrams explaining the code. Definitely worth studying. 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. @@ -157,7 +157,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? +Any subtle features of the code? Where are they used? : If the code has anything subtle and counter-intuitive, it's definitely worth commenting. ## Summary