ব্লকলি স্টাইল গাইড

Google TypeScript শৈলী নির্দেশিকা অনুসরণ করুন।

টাইপস্ক্রিপ্ট এবং ES6-এ স্থানান্তর

Blockly মূলত ES5.1-এ লেখা হয়েছিল Google JavaScript স্টাইল গাইডের পুরনো, তৎকালীন বর্তমান সংস্করণের সাথে সম্মতিতে। সদ্য-লিখিত কোডটি বর্তমান শৈলী নির্দেশিকা মেনে চলতে হবে এবং যেখানে প্রযোজ্য সেখানে let , const , class , destructuring assignment এর মত ES6 ভাষার বৈশিষ্ট্য ব্যবহার করতে হবে। বিদ্যমান কোড আপডেট করা হতে পারে বা সম্মতির বাইরে থাকতে পারে। ব্লকলি টিম অ্যাকাউন্ট কোডের সামঞ্জস্যতা এবং লাইব্রেরির ব্যবহারকারীদের অভিজ্ঞতা বিবেচনা করে সর্বোত্তম সিদ্ধান্ত নেওয়ার চেষ্টা করে - উদাহরণস্বরূপ, আমরা পাবলিক ফাংশনগুলির নাম পরিবর্তন না করতে পারি যেগুলি আর স্টাইল নির্দেশিকা মেনে চলে না৷

করবেন

  • লিন্টিং এবং ফরম্যাটিং টুল ব্যবহার করুন।
    • আমরা eslint ব্যবহার করি এবং একটি .eslintrc.js ফাইল আমাদের পছন্দের শৈলীর নিয়ম সহ সেট আপ করি।
    • আমরা স্বয়ংক্রিয় বিন্যাসের জন্য সুন্দর ব্যবহার করি।
    • লিন্টার চালানোর জন্য npm run lint চালান এবং ফরম্যাটার চালানোর জন্য npm run format ।
  • স্পেস দিয়ে ইন্ডেন্ট করুন, ট্যাব নয়।
  • সেমিকোলন ব্যবহার করুন।
  • ভেরিয়েবল এবং ফাংশনের জন্য camelCase ব্যবহার করুন।
  • ক্লাসের জন্য TitleCase ব্যবহার করুন।
  • ধ্রুবকের জন্য ALL_CAPS ব্যবহার করুন।
  • সমস্ত নিয়ন্ত্রণ কাঠামোর জন্য ধনুর্বন্ধনী ব্যবহার করুন ।
    • ব্যতিক্রম: বিবৃতি if আপনি একক লাইনের জন্য ধনুর্বন্ধনী বাদ দিতে পারেন।
  • একক উদ্ধৃতি ব্যবহার করুন (JSON লেখার সময় ছাড়া)।
  • loops for ভেরিয়েবল পুনরায় ঘোষণা. অর্থাৎ, সর্বদা for (const i = 0; ...) for (i = 0; ...) লিখুন।
    • এটি না করা ঝুঁকি বাড়ায় যে ফাংশনে রিফ্যাক্টর উচ্চতর হওয়ার পরে ভেরিয়েবল অনাথ হয়ে যাবে এবং একটি আশ্চর্যজনক বিশ্বে পরিণত হবে।
  • বড় অক্ষর দিয়ে মন্তব্য শুরু করুন এবং পিরিয়ড দিয়ে শেষ করুন।
  • TODOs এর সাথে GitHub সমস্যা তৈরি করুন এবং TODO(#issueNumber) ব্যবহার করে তাদের লিঙ্ক করুন।
  • TSDoc দিয়ে সবকিছু টীকা করুন।

করবেন না

  • ট্যাব দিয়ে ইন্ডেন্ট করুন।
  • পরিবর্তনশীল বা ফাংশনের নামের শেষে আন্ডারলাইন ব্যবহার করুন।
    • কিছু আগের কোড ব্যক্তিগত বা অভ্যন্তরীণ বৈশিষ্ট্য বা ফাংশনের জন্য আন্ডারস্কোর ব্যবহার করে। যদিও এইগুলি বিদ্যমান থাকতে পারে, এই নিয়ম অনুসরণ করে কোন নতুন কোড যোগ করা উচিত নয়।
  • snake_case ব্যবহার করুন।
  • ডবল কোট ব্যবহার করুন (JSON লেখার সময় ছাড়া)।
  • বিকৃত TSDoc ব্যবহার করুন।
    • আমাদের TSDoc আমাদের ডকুমেন্টেশনের অংশ হিসাবে স্বয়ংক্রিয়ভাবে প্রকাশিত হয়।
  • TODO (username) লিখুন।
    • পরিবর্তে TODO-এর সাথে GitHub সমস্যা তৈরি করুন এবং TODO(#issueNumber) ব্যবহার করে তাদের লিঙ্ক করুন।
  • string.startsWith ব্যবহার করুন। পরিবর্তে Blockly.utils.string.startsWith ব্যবহার করুন।

TSDoc

ব্লকলি টিম আমাদের কোড টীকা করতে এবং ডকুমেন্টেশন তৈরি করতে TSDoc ব্যবহার করে। আমরা ক্লাসের সমস্ত পাবলিক প্রপার্টি এবং সমস্ত এক্সপোর্ট করা ফাংশনের জন্য TSDoc আশা করি।

সঠিকভাবে পার্স করার জন্য TSDoc মন্তব্য অবশ্যই /** দিয়ে শুরু হবে এবং */ দিয়ে শেষ হবে।

প্রকারভেদ

TSDoc থেকে প্রকারগুলি বাদ দেওয়া হয়েছে কারণ সেই তথ্যটি সরাসরি টাইপস্ক্রিপ্ট কোডে রয়েছে৷ আপনি যদি কয়েকটি অবশিষ্ট জাভাস্ক্রিপ্ট ফাইলের একটি সম্পাদনা করছেন, তাহলে ক্লোজার কম্পাইলার ডকুমেন্টেশন অনুযায়ী টাইপ টীকা অন্তর্ভুক্ত করুন।

দৃশ্যমানতা

যে ফাংশন বা বৈশিষ্ট্যগুলি শুধুমাত্র ব্লকলি লাইব্রেরির মধ্যে অ্যাক্সেস করা উচিত তা @internal দিয়ে টীকা করা উচিত। এটি এই বৈশিষ্ট্যগুলিকে পাবলিক ডকুমেন্টেশনে উপস্থিত হতে বাধা দেয়। অন্যান্য দৃশ্যমানতা সংশোধকগুলি সরাসরি টাইপস্ক্রিপ্ট কোডে স্থাপন করা উচিত, TSDoc-এ নয়।

বৈশিষ্ট্য

বৈশিষ্ট্যগুলির জন্য TSDoc-এ সম্পত্তির একটি বিবরণ অন্তর্ভুক্ত করা উচিত। স্ব-ব্যাখ্যামূলক বৈশিষ্ট্যের জন্য বর্ণনাটি বাদ দেওয়া যেতে পারে। 

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

ফাংশন

ফাংশন জন্য টীকা অন্তর্ভুক্ত করা উচিত

  • ফাংশন একটি বিবরণ
  • প্রতি প্যারামিটারে একটি @param ট্যাগ সহ
    • নাম
    • বর্ণনা
  • একটি @returns ট্যাগ যদি ফাংশন একটি মান প্রদান করে, প্রত্যাবর্তিত মানের বিবরণ সহ।

বর্ণনাগুলি ফাংশন, প্যারামিটার বা রিটার্ন মানগুলির জন্য বাদ দেওয়া যেতে পারে যদি সেগুলি স্ব-ব্যাখ্যামূলক হয়।

যেমন:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}