From ef6b5bf8d8b498246e9dc0443eda0a85b8dc79dd Mon Sep 17 00:00:00 2001 From: Baki Ruhunnabi Date: Thu, 4 Mar 2021 17:00:49 +0100 Subject: [PATCH 1/5] Update article.md Section 1 & 2 --- 1-js/03-code-quality/03-comments/article.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 0d11c6c52..2c7be1479 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -1,14 +1,14 @@ -# Comments +# মন্তব্য -As we know from the chapter , comments can be single-line: starting with `//` and multiline: `/* ... */`. +ইতপূর্বে আমরা কোডের গঠন চ্যাপ্টারে দেখেছি যে মন্তব্য এক লাইনের (সিংগেল লাইন) যা `//` দিয়ে শুরু এবং একাধিক লাইনের (মাল্টি লাইন) যা `/* ... */` শুরু হতে পারে. -We normally use them to describe how and why the code works. +সাধারণত আমরা কোডটি কিভাবে এবং কেনো কাজ করছে তার বর্ণনা দেবার জন্য মন্তব্য ব্যাবহার করে থাকি। -At first sight, commenting might be obvious, but novices in programming often use them wrongly. +প্রাথমিকভাবে মন্তব্য সুস্পষ্ট মনে হতে পারে, তবে প্রোগ্রামিং এ নবাগতরা প্রায়শই মন্তব্য ভুলভাবে ব্যবহার করে থাকে। -## Bad comments +## ত্রুটিপূর্ণ মন্তব্য -Novices tend to use comments to explain "what is going on in the code". Like this: +নবাগতদের মাঝে মন্তব্য ব্যবহার করে "এই কোডে কি ঘটছে" তা ব্যাখ্যা করার প্রবণতা দেখা যায়। এরকমঃ ```js // This code will do this thing (...) and that thing (...) @@ -18,9 +18,11 @@ complex; code; ``` -But in good code, the amount of such "explanatory" comments should be minimal. Seriously, the 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". ### Recipe: factor out functions From 0d7593a906f224ab8d15bc89442fab482dde223f Mon Sep 17 00:00:00 2001 From: Baki Ruhunnabi Date: Thu, 4 Mar 2021 21:03:44 +0100 Subject: [PATCH 2/5] Update article.md Done upto line 121 --- 1-js/03-code-quality/03-comments/article.md | 27 +++++++++------------ 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 2c7be1479..5d4f7e507 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -22,11 +22,9 @@ code; এ ব্যাপারে একটি সুন্দর নিয়ম আছেঃ "কোডটি যদি এতটাই অস্পষ্ট হয় যে এর জন্য একটি মন্তব্য প্রয়োজন, তবে সম্ভবত মন্তব্যের পরিবর্তে এটি পুনরায় লেখা উচিত" +### কৌশল: ফাংশন পুনর্গঠন - -### Recipe: factor out functions - -Sometimes it's beneficial to replace a code piece with a function, like here: +অনেক ক্ষেত্রে কোডের অংশবিশেষ এর বদলে ফাংশন ব্যবহার করাটা সুবিধাজনক। যেমনঃ ```js function showPrimes(n) { @@ -45,8 +43,7 @@ function showPrimes(n) { } ``` -The better variant, with a factored out function `isPrime`: - + `isPrime` ফাংশন দিয়ে এর এর শ্রেয়তর বিকল্পঃ ```js function showPrimes(n) { @@ -67,11 +64,11 @@ function isPrime(n) { } ``` -Now we can understand the code easily. The function itself becomes the comment. Such code is called *self-descriptive*. +এখন আমরা খুব সহজেই কোডটি বুঝতে পারছি। ফাংশনটি নিজেই মন্তব্য হিসবে কাজ করছে। এ ধরনের কোড কে বলা হয় "স্ব-বর্ণনামূলক" -### Recipe: create functions +### কৌশলঃ ফাংশন তৈরি -And if we have a long "code sheet" like this: +এবং যদি আমাদের নিচের মত এরকম দীর্ঘ কোড শিট থাকেঃ ```js // here we add whiskey @@ -92,7 +89,7 @@ for(let t = 0; t < 3; t++) { // ... ``` -Then it might be a better variant to refactor it into functions like: +সেক্ষেত্রে শ্রেয়তর বিকল্পের জন্য কোডটি কে নিচের মত ফাংশনে পুনর্ঘঠন করা যেতে পারেঃ ```js addWhiskey(glass); @@ -113,15 +110,15 @@ 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 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 +## ভালো মন্তব্য -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. Document function parameters and usage From 3aa2a8e8f55e899952bc72aae1b7e9e6da5dd42a Mon Sep 17 00:00:00 2001 From: Baki Ruhunnabi Date: Mon, 22 Mar 2021 21:59:45 +0100 Subject: [PATCH 3/5] Update article.md updated --- 1-js/03-code-quality/03-comments/article.md | 35 ++++++++++----------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 5d4f7e507..0bfff9a69 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -43,7 +43,7 @@ function showPrimes(n) { } ``` - `isPrime` ফাংশন দিয়ে এর এর শ্রেয়তর বিকল্পঃ + `isPrime` ফাংশন দিয়ে এর শ্রেয়তর বিকল্পঃ ```js function showPrimes(n) { @@ -118,13 +118,12 @@ function addJuice(container) { সুতরাং, ব্যাখ্যামূলক মন্তব্য সাধারণত খারাপ। সেক্ষেত্রে কোন ধরণের মন্তব্য ভাল? -গঠনপ্রণালী বর্ণনা করুন -: 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. +গঠনপ্রণালী বর্ণনা করুনঃ কম্পোনেন্ট এর সার্বিক একটি রূপরেখা উল্লেখ করুন, এদের পারষ্পরিক মিথষ্ক্রিয়া এবং ভিন্ন ভিন্ন কন্ট্রোল ফ্লো সম্পর্কে বলুন। সংক্ষেপে, কোড এর বার্ডস আই ভিউ। কোড সহজবোধ্য উপস্থাপন করার জন্য সার্বিক রূপরেখা তৈরির বিশেষ ধরনের ল্যাংগুয়েজ [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) রয়েছে। -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. +ফাংশন এর প্যারামিটার এবং ব্যাবহার লিপিবদ্ধ করুনঃ ফাংশন এর প্যারামিটার, ব্যাবহার, রিটার্ন ভ্যালু লিপিবদ্ধ করার জন্য বিশেষ ধরনের ল্যাংগুয়েজ [JSDoc](http://en.wikipedia.org/wiki/JSDoc) রয়েছে। + +উদাহরণস্বরূপঃ -For instance: ```js /** * Returns x raised to the n-th power. @@ -138,26 +137,24 @@ function pow(x, n) { } ``` -Such comments allow us to understand the purpose of the function and use it the right way without looking in its code. +এই ধরনের মন্তব্যের মাধ্যমে আমরা কোড না দেখেই ফাংশনটির কাজ এবং ব্যবহার বুঝতে পারি। -By the way, many editors like [WebStorm](https://www.jetbrains.com/webstorm/) can understand them as well and use them to provide autocomplete and some automatic code-checking. +প্রসঙ্গত উল্লেখ্য, অনেক এডিটর যেমন [WebStorm](https://www.jetbrains.com/webstorm/) এই ধরনের ল্যাংগুয়েজ বুঝতে পারে এবং অটোকমপ্লিট ও স্বয়ংক্রিয় কোড-পরীক্ষায় তা ব্যবহার করে থাকে। -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 . +এছাড়াও, মন্তব্য থেকে এইচটিএমএল-ডকুমেন্টেশন তৈরির জন্য [JSDoc 3](https://github.com/jsdoc3/jsdoc) এর মত টুল রয়েছে। JSDoc সম্পর্কে আরো জানতে দেখতে পারেন। -Why is the task solved this way? -: 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. + যদি কাজটি সমাধানের অনেকগুলো উপায় থাকে, সেক্ষেত্রে কেনো এইটি? বিশেষভাবে যখন এটি আপাতদৃষ্টিতে সবচেয়ে সুস্পষ্ট সমাধান নয় - Without such comments the following situation is possible: - 1. You (or your colleague) open the code written some time ago, and see that it's "suboptimal". - 2. You think: "How stupid I was then, and how much smarter I'm now", and rewrite using the "more obvious and correct" variant. - 3. ...The urge to rewrite was good. But in the process you see that the "more obvious" solution is actually lacking. You even dimly remember why, because you already tried it long ago. You revert to the correct variant, but the time was wasted. + এইধরনের মন্তব্য ছাড়া নিম্নলিখিত পরস্থিতি হতে পারেঃ + ১। আপনি অথবা আপনার সহকর্মীরা কিছুক্ষণ পূর্বে লিখিত কোডটি দেখলেন এবং ভাবলেন কোডটি সাব-অপটিমাল + ২। আপনি ভাবলেনঃ " আমি কতটা বোকাটা ছিলাম,আর এখন কতটা বুদ্ধিমান ", এবং "আরো সুস্পষ্ট এবং সঠিক" বিকল্প ব্যবহার করে পুনরায় কোডটি লিখলেন + ৩। ... কোড পুনরায় লেখার তাগিদ থাকা ভালো। কিন্তু কাজকরার প্রক্রিয়াআপনি দেখলেন "অধিক সুস্পষ্ট" সমাধানটি তে আসলে ঘাটতি রয়েছে। এমনকি আপনি খুব অস্পষ্টভাবে মনে করতে পারবেন কেনো এমন হচ্ছে, কারণ আপনি অনেক সময় আগে এই চেষ্টা করেছেন। আপনি আবার সঠিক বিকল্পে ফিরে আসবেন কিন্তু এর মাঝে কিছু সময় অপচয় হলো। - 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-intuitive, it's definitely worth commenting. +কোড এ কোন সূক্ষ্ম বৈশিষ্ট রয়েছে? কেনো এই ধরনের বৈশিষ্ট ব্যবহার করা হয়েছে?: If the code has anything subtle and counter-intuitive, it's definitely worth commenting. ## Summary From 48f11074e8816de8848b172256d969a940d3bb3e Mon Sep 17 00:00:00 2001 From: Baki Ruhunnabi Date: Mon, 22 Mar 2021 22:46:22 +0100 Subject: [PATCH 4/5] Update article.md last updated --- 1-js/03-code-quality/03-comments/article.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 0bfff9a69..76ca1c12f 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -154,23 +154,23 @@ function pow(x, n) { সমাধান কে ব্যখ্যাকারী মন্তব্য খুব গুরুত্বপূর্ণ। এই ধরনের মন্তব্য সঠিক প্রক্রিয়ায় ডেভেলপমেন্ট করতে সাহাজ্য করে। -কোড এ কোন সূক্ষ্ম বৈশিষ্ট রয়েছে? কেনো এই ধরনের বৈশিষ্ট ব্যবহার করা হয়েছে?: If the code has anything subtle and counter-intuitive, it's definitely worth commenting. +কোড এ কোন সূক্ষ্ম বৈশিষ্ট রয়েছে? কেনো এই ধরনের বৈশিষ্ট ব্যবহার করা হয়েছে?: যদি কোড এ কোন সূক্ষ্ম অথবা সহজাত নয় এরকম কিছু থাকে তা অবশ্যই মন্তব্যে অন্তর্ভূক্ত করা উচিত। -## Summary +## সারসংক্ষেপ -An important sign of a good developer is comments: their presence and even their absence. +মন্তব্য এর উপস্থিতি/অনুপস্থিতি একজন ভালো ডেভেলপার এর বৈশিষ্ট। -Good comments allow us to maintain the code well, come back to it after a delay and use it more effectively. +ভালো মন্তব্য আমাদের সঠিকভাবে কোড রক্ষণাবেক্ষণ এবং কিছু সময় এর ব্যবধানে কোডটিকে কার্যকরভাবে ব্যবহার করতে সাহাজ্য করে। -**Comment this:** +**মন্তব্য করুনঃ** -- Overall architecture, high-level view. -- Function usage. -- Important solutions, especially when not immediately obvious. +- সামগ্রিক গঠনকৌশল, বাহ্যিক কাঠামো। +- ফাংশনের ব্যবহার। +- গুরুত্বপূর্ণ সমাধান, বিশেষভাবে যখন তা সুস্পষ্টভাবে প্রতীয়মান নয়। -**Avoid comments:** +**মন্তব্য পরিত্যাগ করুনঃ** -- That tell "how code works" and "what it does". -- Put them in only if it's impossible to make the code so simple and self-descriptive that it doesn't require them. +- যে মন্তব্য "কোড কিভাবে কাজ করে" এবং "কি কাজ করে" সেটা উপস্থাপন করে। +- সহজ এবং স্ব-ব্যখ্যায়িত কোড, যা তে মন্তব্য প্রয়োজন হয় না, তা যদি অসম্ভব হয় কেবলমাত্র সেক্ষেত্রে মন্তব্য করুন। -Comments are also used for auto-documenting tools like JSDoc3: they read them and generate HTML-docs (or docs in another format). +অধিকন্ত JSDoc3 এর মত স্বয়ংক্রিয়-লিপিবদ্ধ করার টুল () কাজে মন্তব্য ব্যবহার করা হয়ে থাকে। এরা মন্তব্য থেকে এইচটিএমএল ডকুমেন্ট তৈরি করে (অথবা অন্য কোন ফরম্যাট এর ডকুমেন্ট) From c35e4515e8b31e8e4d36336ebac61926fa166d87 Mon Sep 17 00:00:00 2001 From: Baki Ruhunnabi Date: Sat, 17 Apr 2021 17:56:57 +0200 Subject: [PATCH 5/5] Update article.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit মন্তব্য changed to কমেন্ট as suggested by the reviewer --- 1-js/03-code-quality/03-comments/article.md | 48 ++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 76ca1c12f..4ff5a0ecc 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -1,14 +1,14 @@ -# মন্তব্য +# কমেন্ট -ইতপূর্বে আমরা কোডের গঠন চ্যাপ্টারে দেখেছি যে মন্তব্য এক লাইনের (সিংগেল লাইন) যা `//` দিয়ে শুরু এবং একাধিক লাইনের (মাল্টি লাইন) যা `/* ... */` শুরু হতে পারে. +ইতপূর্বে আমরা কোডের গঠন চ্যাপ্টারে দেখেছি যে কমেন্ট এক লাইনের (সিংগেল লাইন) যা `//` দিয়ে শুরু এবং একাধিক লাইনের (মাল্টি লাইন) যা `/* ... */` শুরু হতে পারে. -সাধারণত আমরা কোডটি কিভাবে এবং কেনো কাজ করছে তার বর্ণনা দেবার জন্য মন্তব্য ব্যাবহার করে থাকি। +সাধারণত আমরা কোডটি কিভাবে এবং কেনো কাজ করছে তার বর্ণনা দেবার জন্য কমেন্ট ব্যাবহার করে থাকি। -প্রাথমিকভাবে মন্তব্য সুস্পষ্ট মনে হতে পারে, তবে প্রোগ্রামিং এ নবাগতরা প্রায়শই মন্তব্য ভুলভাবে ব্যবহার করে থাকে। +প্রাথমিকভাবে কমেন্ট সুস্পষ্ট মনে হতে পারে, তবে প্রোগ্রামিং এ নবাগতরা প্রায়শই কমেন্ট ভুলভাবে ব্যবহার করে থাকে। -## ত্রুটিপূর্ণ মন্তব্য +## ত্রুটিপূর্ণ কমেন্ট -নবাগতদের মাঝে মন্তব্য ব্যবহার করে "এই কোডে কি ঘটছে" তা ব্যাখ্যা করার প্রবণতা দেখা যায়। এরকমঃ +নবাগতদের মাঝে কমেন্ট ব্যবহার করে "এই কোডে কি ঘটছে" তা ব্যাখ্যা করার প্রবণতা দেখা যায়। এরকমঃ ```js // This code will do this thing (...) and that thing (...) @@ -18,9 +18,9 @@ complex; code; ``` -কিন্ত ভালো কোডে এরকম "ব্যাখ্যামূলক" মন্তব্যের উপস্থিতি হওয়া উচিৎ ন্যূনতম। মন্তব্য ছাড়াই কোড সহজবোধ্য হওয়াটা গুরুত্বপূর্ণ। +কিন্ত ভালো কোডে এরকম "ব্যাখ্যামূলক" কমেন্টে এর উপস্থিতি হওয়া উচিৎ ন্যূনতম। কমেন্ট ছাড়াই কোড সহজবোধ্য হওয়াটা গুরুত্বপূর্ণ। -এ ব্যাপারে একটি সুন্দর নিয়ম আছেঃ "কোডটি যদি এতটাই অস্পষ্ট হয় যে এর জন্য একটি মন্তব্য প্রয়োজন, তবে সম্ভবত মন্তব্যের পরিবর্তে এটি পুনরায় লেখা উচিত" +এ ব্যাপারে একটি সুন্দর নিয়ম আছেঃ "কোডটি যদি এতটাই অস্পষ্ট হয় যে এর জন্য একটি কমেন্ট প্রয়োজন, তবে সম্ভবত কমেন্ট এর পরিবর্তে এটি পুনরায় লেখা উচিত" ### কৌশল: ফাংশন পুনর্গঠন @@ -64,7 +64,7 @@ function isPrime(n) { } ``` -এখন আমরা খুব সহজেই কোডটি বুঝতে পারছি। ফাংশনটি নিজেই মন্তব্য হিসবে কাজ করছে। এ ধরনের কোড কে বলা হয় "স্ব-বর্ণনামূলক" +এখন আমরা খুব সহজেই কোডটি বুঝতে পারছি। ফাংশনটি নিজেই কমেন্ট হিসবে কাজ করছে। এ ধরনের কোড কে বলা হয় "স্ব-বর্ণনামূলক" ### কৌশলঃ ফাংশন তৈরি @@ -110,13 +110,13 @@ function addJuice(container) { } ``` -ফাংশন নিজেরাই কি ঘটছে ব্যাখ্যা করে। এখানে মন্তব্য লেখার কিছু নেই। এছাড়াও আলাদা আলাদা থাকলে কোডের গঠন ভালো হয়। এটা সুপষ্ট যে প্রতিটি ফাংশন কি করে, কি গ্রহণ করে এবং কি রিটার্ন করে। +ফাংশন নিজেরাই কি ঘটছে ব্যাখ্যা করে। এখানে কমেন্ট লেখার কিছু নেই। এছাড়াও আলাদা আলাদা থাকলে কোডের গঠন ভালো হয়। এটা সুপষ্ট যে প্রতিটি ফাংশন কি করে, কি গ্রহণ করে এবং কি রিটার্ন করে। -বাস্তবে,আমরা সম্পুর্ণরূপে ব্যখ্যা সম্বলিত মন্তব্য পরিহার করতে পারি না। এখানে উৎকর্ষতা সাধনের জন্য অনেক জটিল অ্যালগরিদম এবং অনেক সুক্ষ্ম সমন্বয় করা হয়। কিন্ত সাধারণভাবে আমাদের উচিৎ কোড কে সহজ-সরল এবং স্ব-বর্ণ্নামূলক রাখার জন্য চেষ্টা করা । +বাস্তবে,আমরা সম্পুর্ণরূপে ব্যখ্যা সম্বলিত কমেন্ট পরিহার করতে পারি না। এখানে উৎকর্ষতা সাধনের জন্য অনেক জটিল অ্যালগরিদম এবং অনেক সুক্ষ্ম সমন্বয় করা হয়। কিন্ত সাধারণভাবে আমাদের উচিৎ কোড কে সহজ-সরল এবং স্ব-বর্ণ্নামূলক রাখার জন্য চেষ্টা করা । -## ভালো মন্তব্য +## ভালো কমেন্ট -সুতরাং, ব্যাখ্যামূলক মন্তব্য সাধারণত খারাপ। সেক্ষেত্রে কোন ধরণের মন্তব্য ভাল? +সুতরাং, ব্যাখ্যামূলক কমেন্ট সাধারণত খারাপ। সেক্ষেত্রে কোন ধরণের কমেন্ট ভালো? গঠনপ্রণালী বর্ণনা করুনঃ কম্পোনেন্ট এর সার্বিক একটি রূপরেখা উল্লেখ করুন, এদের পারষ্পরিক মিথষ্ক্রিয়া এবং ভিন্ন ভিন্ন কন্ট্রোল ফ্লো সম্পর্কে বলুন। সংক্ষেপে, কোড এর বার্ডস আই ভিউ। কোড সহজবোধ্য উপস্থাপন করার জন্য সার্বিক রূপরেখা তৈরির বিশেষ ধরনের ল্যাংগুয়েজ [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) রয়েছে। @@ -137,40 +137,40 @@ function pow(x, n) { } ``` -এই ধরনের মন্তব্যের মাধ্যমে আমরা কোড না দেখেই ফাংশনটির কাজ এবং ব্যবহার বুঝতে পারি। +এই ধরনের কমেন্ট এর মাধ্যমে আমরা কোড না দেখেই ফাংশনটির কাজ এবং ব্যবহার বুঝতে পারি। প্রসঙ্গত উল্লেখ্য, অনেক এডিটর যেমন [WebStorm](https://www.jetbrains.com/webstorm/) এই ধরনের ল্যাংগুয়েজ বুঝতে পারে এবং অটোকমপ্লিট ও স্বয়ংক্রিয় কোড-পরীক্ষায় তা ব্যবহার করে থাকে। -এছাড়াও, মন্তব্য থেকে এইচটিএমএল-ডকুমেন্টেশন তৈরির জন্য [JSDoc 3](https://github.com/jsdoc3/jsdoc) এর মত টুল রয়েছে। JSDoc সম্পর্কে আরো জানতে দেখতে পারেন। +এছাড়াও, কমেন্ট থেকে এইচটিএমএল-ডকুমেন্টেশন তৈরির জন্য [JSDoc 3](https://github.com/jsdoc3/jsdoc) এর মত টুল রয়েছে। JSDoc সম্পর্কে আরো জানতে দেখতে পারেন। কাজটি কেনো এভাবে সমাধান করা হয়েছে? : যা লিখিত থাকে তা গুরুত্বপূর্ণ। তবে যা *অলিখিত* সেটা কি ঘটছে তা বোঝার জন্য অধিক গুরুত্বপূর্ণ হতে পারে। এই কাজটি কেনো ঠিক এইভাবেই সমাধান করা হয়েছে? এক্ষেত্রে কোড কোন উত্তর দেয় না। যদি কাজটি সমাধানের অনেকগুলো উপায় থাকে, সেক্ষেত্রে কেনো এইটি? বিশেষভাবে যখন এটি আপাতদৃষ্টিতে সবচেয়ে সুস্পষ্ট সমাধান নয় - এইধরনের মন্তব্য ছাড়া নিম্নলিখিত পরস্থিতি হতে পারেঃ + এইধরনের কমেন্ট ছাড়া নিম্নলিখিত পরস্থিতি হতে পারেঃ ১। আপনি অথবা আপনার সহকর্মীরা কিছুক্ষণ পূর্বে লিখিত কোডটি দেখলেন এবং ভাবলেন কোডটি সাব-অপটিমাল ২। আপনি ভাবলেনঃ " আমি কতটা বোকাটা ছিলাম,আর এখন কতটা বুদ্ধিমান ", এবং "আরো সুস্পষ্ট এবং সঠিক" বিকল্প ব্যবহার করে পুনরায় কোডটি লিখলেন ৩। ... কোড পুনরায় লেখার তাগিদ থাকা ভালো। কিন্তু কাজকরার প্রক্রিয়াআপনি দেখলেন "অধিক সুস্পষ্ট" সমাধানটি তে আসলে ঘাটতি রয়েছে। এমনকি আপনি খুব অস্পষ্টভাবে মনে করতে পারবেন কেনো এমন হচ্ছে, কারণ আপনি অনেক সময় আগে এই চেষ্টা করেছেন। আপনি আবার সঠিক বিকল্পে ফিরে আসবেন কিন্তু এর মাঝে কিছু সময় অপচয় হলো। - সমাধান কে ব্যখ্যাকারী মন্তব্য খুব গুরুত্বপূর্ণ। এই ধরনের মন্তব্য সঠিক প্রক্রিয়ায় ডেভেলপমেন্ট করতে সাহাজ্য করে। + সমাধান কে ব্যখ্যাকারী কমেন্ট খুব গুরুত্বপূর্ণ। এই ধরনের কমেন্ট সঠিক প্রক্রিয়ায় ডেভেলপমেন্ট করতে সাহাজ্য করে। কোড এ কোন সূক্ষ্ম বৈশিষ্ট রয়েছে? কেনো এই ধরনের বৈশিষ্ট ব্যবহার করা হয়েছে?: যদি কোড এ কোন সূক্ষ্ম অথবা সহজাত নয় এরকম কিছু থাকে তা অবশ্যই মন্তব্যে অন্তর্ভূক্ত করা উচিত। ## সারসংক্ষেপ -মন্তব্য এর উপস্থিতি/অনুপস্থিতি একজন ভালো ডেভেলপার এর বৈশিষ্ট। +কমেন্ট এর উপস্থিতি/অনুপস্থিতি একজন ভালো ডেভেলপার এর বৈশিষ্ট। -ভালো মন্তব্য আমাদের সঠিকভাবে কোড রক্ষণাবেক্ষণ এবং কিছু সময় এর ব্যবধানে কোডটিকে কার্যকরভাবে ব্যবহার করতে সাহাজ্য করে। +ভালো কমেন্ট আমাদের সঠিকভাবে কোড রক্ষণাবেক্ষণ এবং কিছু সময় এর ব্যবধানে কোডটিকে কার্যকরভাবে ব্যবহার করতে সাহাজ্য করে। -**মন্তব্য করুনঃ** +**কমেন্ট করুনঃ** - সামগ্রিক গঠনকৌশল, বাহ্যিক কাঠামো। - ফাংশনের ব্যবহার। - গুরুত্বপূর্ণ সমাধান, বিশেষভাবে যখন তা সুস্পষ্টভাবে প্রতীয়মান নয়। -**মন্তব্য পরিত্যাগ করুনঃ** +**কমেন্ট পরিত্যাগ করুনঃ** -- যে মন্তব্য "কোড কিভাবে কাজ করে" এবং "কি কাজ করে" সেটা উপস্থাপন করে। -- সহজ এবং স্ব-ব্যখ্যায়িত কোড, যা তে মন্তব্য প্রয়োজন হয় না, তা যদি অসম্ভব হয় কেবলমাত্র সেক্ষেত্রে মন্তব্য করুন। +- যে কমেন্ট "কোড কিভাবে কাজ করে" এবং "কি কাজ করে" সেটা উপস্থাপন করে। +- সহজ এবং স্ব-ব্যখ্যায়িত কোড, যা তে কমেন্ট প্রয়োজন হয় না, তা যদি অসম্ভব হয় কেবলমাত্র সেক্ষেত্রে কমেন্ট করুন। -অধিকন্ত JSDoc3 এর মত স্বয়ংক্রিয়-লিপিবদ্ধ করার টুল () কাজে মন্তব্য ব্যবহার করা হয়ে থাকে। এরা মন্তব্য থেকে এইচটিএমএল ডকুমেন্ট তৈরি করে (অথবা অন্য কোন ফরম্যাট এর ডকুমেন্ট) +অধিকন্ত JSDoc3 এর মত স্বয়ংক্রিয়-লিপিবদ্ধ করার টুল () কাজে কমেন্ট ব্যবহার করা হয়ে থাকে। এরা কমেন্ট থেকে এইচটিএমএল ডকুমেন্ট তৈরি করে (অথবা অন্য কোন ফরম্যাট এর ডকুমেন্ট)