অ্যানালাইজার কমেন্ট লেখা

এই ডকুমেন্টে অ্যানালাইজার যে কমেন্ট তৈরি করে, সেগুলো কীভাবে লিখবেন তা নিয়ে তথ্য ও নির্দেশনা দেওয়া হয়েছে।

বিষয়সূচি

অ্যানালাইজার কমেন্টের কনটেন্ট exercism/website-copy রিপোতে Markdown ডকুমেন্ট হিসেবে সংরক্ষিত থাকে। প্রতিটি কমেন্টে একটি পয়েন্টার-স্ট্রিং থাকে, যার ফরম্যাট <track-slug>.<exercise-slug>.<comment-slug>, এবং এটি website-copy রিপোর একটি নির্দিষ্ট Markdown ডকুমেন্টে লিংক করে।

উদাহরণস্বরূপ, ruby.two-fer.string-interpolation বলতে বোঝায় https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md।

শব্দচয়ন

• অপ্রয়োজনীয়ভাবে বাহুল্য কমেন্ট লেখা এড়িয়ে চলুন। সংক্ষিপ্ত থাকুন।
• নিরপেক্ষ দৃষ্টিতে পর্যবেক্ষণ করুন; আবেগপ্রবণ বক্তব্য এবং ব্যাপক সাধারণীকরণ এড়িয়ে চলুন।
• সুপারিশটি স্পষ্ট করে বলুন।
• সম্ভব হলে আগে সুপারিশ দিন, তারপর ব্যাখ্যা।
• "me", "I", "we" ইত্যাদি এড়িয়ে চলুন, কারণ বট কোনো মানুষ নয়।
• "you" এবং "your code" ব্যবহার করা এড়িয়ে চলুন, কারণ এতে কখনও কখনও কোডের বদলে ব্যক্তিকেই বিচার করা বোঝায়।
• "just", "simply", "obviously" জাতীয় শব্দ এড়িয়ে চলুন, কারণ এগুলো করুণার সুরে বলা মনে হতে পারে: মন্তব্যটি যদি দরকারি হয়, তাহলে এটা obviously obvious ছিল না।
• মানুষ কী জানে আর কী জানে না, তা নিয়ে অনুমান করা এড়িয়ে চলুন। এর একমাত্র ব্যতিক্রম হলো আগে সম্পন্ন করা core অনুশীলনীগুলো থেকে পাওয়া জ্ঞান। "as you know", "as you remember", "as you learned", "now that we all understand x" জাতীয় কথা এড়িয়ে চলুন, কারণ কোনো কিছু বলা হলেও ব্যক্তি সেটি বুঝেছে কি না তা নিশ্চিত নয়।

নির্দেশনা

• লক্ষ্য রাখুন সাবলীলতা, পারদর্শিতা নয়: Exercism-এ একটি ভাষার ট্র্যাকে লক্ষ্য হলো মানুষকে এমন একটি পথ দেওয়া যাতে তারা কম পারদর্শিতাতেই উচ্চমাত্রার সাবলীলতা অর্জন করতে পারে। আমরা লক্ষ্য রাখি ভাষার সিনট্যাক্স, ইডিয়ম এবং স্ট্যান্ডার্ড লাইব্রেরিতে সাবলীলতা।
• সম্ভব হলে ইডিয়ম্যাটিক কোডের পরামর্শ দিন, যেখানে ইডিয়ম্যাটিক বলতে এমন কোড বোঝায় যা ওই ভাষায় কোড লেখেন এমন প্রায় সব ডেভেলপার (শখের বশে নয়, যারা পেশাদারভাবে লেখেন) লিখে থাকেন। কোনো পরামর্শ ইডিয়ম্যাটিক না হলে সেটি উল্লেখ করুন এবং কেন পরামর্শটি তবুও কাজে লাগতে পারে তা ব্যাখ্যা করুন।
• ব্যক্তিটি যা করছেন এবং ভাষায় যা 'ইডিয়ম্যাটিক', তার মধ্যে পার্থক্যটি তুলে ধরুন।
• সঠিক পরিভাষা ও নামকরণ ব্যবহার করুন, যাতে মানুষ ধারণাগুলো অন্য জায়গায় চিনতে পারে এবং নিজেরাই সেগুলো নিয়ে খোঁজ করতে পারে।
• Exercism-এ সব মেন্টরিংয়ের সাধারণ নিয়ম হিসেবে সমাধানটি বলে দেবেন না। মানুষ যখন নিজে থেকেই উত্তরটি খুঁজে পায়, তখন শেখাটা মনে গেঁথে যায়। এটি দারুণ রোমাঞ্চকর একটি অভিজ্ঞতা, আর এই আবেগের ঝাঁকুনিই এটিকে স্মরণীয় করে তোলে। তবে সেই আবিষ্কার যদি ডোপামিনের ঝাঁকুনি না দেয়, তাহলে সমাধানটি কেমন দেখতে হয় তা দেখানো একেবারে যুক্তিসঙ্গত। উদাহরণস্বরূপ, অনুমোদিত কোনো সমাধানে ছোট একটি উন্নতির পরামর্শ দেওয়া, বাতিল হওয়া কোনো সমাধানে শেখার একটি বিষয় তুলে ধরার চেয়ে অনেক কম উত্তেজনাপূর্ণ হতে পারে, আর সেক্ষেত্রে লিংকের বদলে একটি উদাহরণ দেওয়াই বাঞ্ছনীয়।
• গুরুত্ব অনুযায়ী কমেন্ট সাজান, প্রথম কমেন্টটি সবচেয়ে গুরুত্বপূর্ণ আর শেষ কমেন্টটি সবচেয়ে কম গুরুত্বপূর্ণ।
• কমেন্টের সংখ্যা সহনীয় রাখুন। প্রতি ইটারেশনে এক থেকে তিনটি কমেন্টের লক্ষ্য রাখুন।
• এক বিশ্লেষণে একই কমেন্ট দুবার যোগ করবেন না। একই কমেন্টের সঙ্গে ভিন্ন প্যারামিটার যুক্ত করলে সেটি ডুপ্লিকেট হিসেবে ধরা হয় না।
• ভাষায় ফরম্যাটিং বা লিন্টিং অবিচ্ছেদ্য অংশ হলে কেবল ফরম্যাটিং নিয়ে কমেন্ট করার কথা ভাবুন। সম্ভব হলে শিক্ষার্থীদের অটো-ফরম্যাটিং টুলের দিকে নির্দেশ দিন এবং/অথবা অফিসিয়াল স্টাইল গাইডের লিংক দিন।

প্রথম কয়েকটি অনুশীলনী

একটি ট্র্যাকের প্রথম কয়েকটি অনুশীলনীর ক্ষেত্রে নিচের বিষয়গুলো বিশেষভাবে গুরুত্বপূর্ণ:

• তুলনামূলকভাবে সংক্ষিপ্ত রাখুন, একটানা লম্বা লেখা বা উপদেশের বন্যা দিয়ে তাদের অভিভূত করা এড়িয়ে চলুন। প্রথম অনুশীলনীতেই যদি তাদের অভিজ্ঞতা ভালো হয়, তারা ফিরে আসবে, আর আপনি যা লক্ষ করেছেন তা নিয়ে ফিডব্যাক দেওয়ার অনেক সুযোগ পাবেন।
• কোনো ধারণা অতিরিক্ত ব্যাখ্যা করবেন না: কম্পাইলারের ভেতরের কার্যপ্রণালী ইত্যাদি নিয়ে গভীরে যাবেন না। এখানে মূল বিষয় হলো এটি ভাষার ট্র্যাকের প্রথম দিকের একটি অনুশীলনী, আর এই পর্যায়ে ফিডব্যাক সংক্ষিপ্ত ও বেশি নির্দেশনামূলক হলে বেশি কাজে লাগে।
• একটি লিংক দিন যেখানে ঠিক কীভাবে ধারণাটি করতে হবে তা টিউটোরিয়াল ধাঁচে দেখানো আছে। অর্থাৎ, কেন করতে হবে তা আলোচনা নয়, কীভাবে করতে হবে তা দেখানো। এর মানে হতে পারে ভাষার অফিসিয়াল ডকুমেন্টেশন যথেষ্ট নয়, কারণ সেগুলো প্রায়ই কেবল কোড রেফারেন্স, কীভাবে ব্যবহার করতে হবে আর কীভাবে কাজ করে তা দেখায় না। তবে, আরও গভীরে জানার জন্যই কেবল লিংক দেওয়া উচিত। লিংক অনুসরণ না করেও যেন ব্যক্তি সরাসরি উত্তরটি পড়েই আপনার বক্তব্য বুঝতে পারে।

উদাহরণ

JavaScript-এ একজন শিক্ষার্থী let দিয়ে একটি টপ-লেভেল কনস্ট্যান্ট লিখেছে।

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

এই কমেন্টটি নিচের কারণে এই নির্দেশনা মানছে না:

• আসল কাজটির কথা বলা হয়েছে "ব্যাখ্যা"-র পরে।
• "As you know": শিক্ষার্থী আসলেই জানে কি না, আমরা জানি না।
• "you shouldn't": কথাটি বলার জন্য "you" রাখার দরকার নেই।
• "everyone uses const": এটি সত্যি নয়, আর এতে শিক্ষার্থীর মনে হতে পারে সে ভীষণ ভুল কিছু করেছে।
• পরামর্শটি কেন দেওয়া হচ্ছে তার প্রকৃত ব্যাখ্যা নেই।

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

Go-তে একজন শিক্ষার্থী বিল্ট-ইন এরর ব্যবহার না করে একটি কাস্টম error তৈরি করেছে:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

এই কমেন্টটি নিচের কারণে এই নির্দেশনা মানছে না:

• "I see": অ্যানালাইজার কোনো মানুষ নয়, তাই I এড়িয়ে চলুন।
• "This is perfectly fine!": তা হলে তো ঠিকই আছে, নইলে আশ্বস্ত করার দরকার পড়ত না। বাক্যটি সম্ভবত পুরোপুরি বাদ দেওয়াই যায়; কোনো কিছু আছে বলে সাধারণ একটি টিপ দিতে চাইলে ঠিক সেটাই বলুন: "An alternative, equally valid way of doing x is y."
• "If you did not know about": অতিরিক্ত বাহুল্য এই শব্দগুচ্ছটি বাদ দিন।

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

কমেন্টগুলো অ্যানালাইজারের সঙ্গে একই রিপোজিটরিতে থাকে না, তাই প্রতিটি অ্যানালাইজারে এমন CI থাকা উচিত যা যাচাই করে যে ওই নির্দিষ্ট অ্যানালাইজারে ব্যবহৃত কমেন্টগুলো (যেগুলো আউটপুট হতে পারে) exercism/website-copy রিপোজিটরির main ব্রাঞ্চের কমেন্ট কি না।

এই লেখার সময়ে, এই CI-এর কোনো সাধারণীকরণ হয়ে থাকলে তার অবস্থা এই ইস্যুতে ট্র্যাক করা হচ্ছে।