From a3472d394443fa5e8a17f2a68a340178dd77585d Mon Sep 17 00:00:00 2001 From: Brent Guffens Date: Fri, 19 Jan 2018 14:19:19 +0100 Subject: [PATCH 1/5] Typos --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 4f187129..d4567e5c 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -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". From 504e5a7e34d9db711de6d7e7b5529f908f6f80e5 Mon Sep 17 00:00:00 2001 From: Brent Guffens Date: Fri, 19 Jan 2018 14:21:17 +0100 Subject: [PATCH 2/5] evade -> avoid --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index d4567e5c..480bffe3 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -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 From 6ed86c957fda153f7db76c535d2f149a4a08f64c Mon Sep 17 00:00:00 2001 From: Brent Guffens Date: Fri, 19 Jan 2018 14:23:48 +0100 Subject: [PATCH 3/5] Typo --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 480bffe3..2683f139 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -146,7 +146,7 @@ Document a function usage Also, there are tools like [JSDoc 3](https://github.com/jsdoc3/jsdoc) that can generate HTML-documentation from the comments. You can read more information about JSDoc at . Why is the task solved this way? -: What's written is important. But what's *not* written maybe even more important to understand what's going on. Why is the task solved exactly this way? The code gives no answer. +: What's written is important. But what's *not* written may be even more important to understand what's going on. Why is the task solved exactly this way? The code gives no answer. If there are many ways to solve the task, why this one? Especially when it's not the most obvious one. From d245e4f10f179f08f2337ea8f158b143c740adee Mon Sep 17 00:00:00 2001 From: Brent Guffens Date: Fri, 19 Jan 2018 14:26:49 +0100 Subject: [PATCH 4/5] Wording --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 2683f139..082e9889 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -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 From cdf7aac0b9244c347875e72bb5aab782881c4d11 Mon Sep 17 00:00:00 2001 From: Brent Guffens Date: Fri, 19 Jan 2018 14:27:29 +0100 Subject: [PATCH 5/5] evade -> avoid --- 1-js/03-code-quality/03-comments/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 082e9889..744751cc 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -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.