মন্তব্য লেখার জন্য শিক্ষানবিশ গাইড?


27

কোড কমেন্টস লেখার জন্য একটি নির্দিষ্ট নির্দেশিকা আছে কি, উদীয়মান বিকাশকারীদের লক্ষ্য করে?

আদর্শভাবে, মন্তব্যগুলি ব্যবহার করা উচিত (এবং না করা উচিত) এবং কোন মন্তব্যে থাকতে হবে তা কভার করবে।

এই উত্তর :

আপনি কী করছেন সে সম্পর্কে মন্তব্য করবেন না, তবে আপনি এটি কেন করছেন।

এটিকে সমর্থন করার জন্য ভেরিয়েবলের যথাযথ পছন্দ সহ পরিষ্কার, পঠনযোগ্য এবং সাধারণ কোড দ্বারা WHAT এর যত্ন নেওয়া হয়। মন্তব্যগুলি কোডটিতে একটি উচ্চ স্তরের কাঠামো দেখায় যা কোডের দ্বারা দেখা যায় না (বা কঠিন) show

কাছাকাছি আসে, তবে এটি অনভিজ্ঞ প্রোগ্রামারদের জন্য কিছুটা সংক্ষিপ্ত আকারে (আমার মনে হয় এটির বেশ কয়েকটি উদাহরণ এবং কোণার কেসগুলির সাথে এর বিস্তৃতি চমৎকার হবে)।

আপডেট : এখানে উত্তরগুলি ছাড়াও, আমি মনে করি যে অন্য প্রশ্নের এই উত্তরটি অত্যন্ত প্রাসঙ্গিক।


আমি মনে করি আমরা দ্রুত এমন একটি পৃথিবীতে চলে যাচ্ছি যেখানে লোকেরা আর কোনও মন্তব্য করে না। আরও ভাল (আরও সম্ভবত) খারাপ জন্য। কর্মতত্পর.
MK01

1
@ এমকে: যদি সে ক্ষেত্রে হয় (আমি এই উত্তরটির সাথে আরও একমত হতে চাই ), তবে কোনও মন্তব্য কীভাবে লিখবেন না এবং কেন সেগুলি এড়ানো উচিত, সে সম্পর্কে একটি গাইড ঠিক ততটাই কার্যকর হবে। প্রকৃতপক্ষে, যত বেশি ভিন্ন দৃষ্টিভঙ্গি তত ভাল।
ক্যামেরন

আমি মনে করি কোড পড়ার গতি উন্নত করতে ছোট মন্তব্যগুলি খুব সহায়ক এবং সর্বদা থাকবে। আমি "বাসি মন্তব্য" যুক্তিটি পুরোপুরি কিনতে পারি না, তারা বাসি হলেও তাদের historicতিহাসিক মূল্য থাকবে। আমি এমন একটি কোড বেসে কাজ করতাম যা মাঝেমধ্যে এখানে এবং সেখানে বিশদ মন্তব্য ছিল এবং মন্তব্যটির মেয়াদোত্তীর্ণ সমস্যার কারণে আসলেই কখনও আমার কামড়ায় না।
MK01

উত্তর:


38

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

সুতরাং কোড কী করছে তা নথিভুক্ত করবেন না। স্ব-ডকুমেন্টিং কোডটি এটির যত্ন নেওয়া উচিত। আপনি এটি করছেন কেন নথি। WHW এর সাধারণত ব্যবসায়িক নিয়ম সম্পর্কিত বা আর্কিটেকচার সম্পর্কিত হয় এবং প্রায়শই পরিবর্তন হয় না এবং WHAT এ দ্রুত বাসি হয় না। নথির প্রান্তের কেস দলিল ব্যতিক্রম। নথি নকশা সিদ্ধান্ত। এবং সর্বাধিক গুরুত্বপূর্ণভাবে আপনি সেই ডিজাইন সিদ্ধান্তগুলি নথিভুক্ত করেছেন যা আপনি বিবেচনা করেছিলেন, কিন্তু বাস্তবায়ন না করার সিদ্ধান্ত নিয়েছেন (এবং ডকুমেন্ট কেন আপনি সেগুলি ব্যবহারের বিরুদ্ধে সিদ্ধান্ত নিয়েছেন)।


2
শেষটি খুব গুরুত্বপূর্ণ। কখনও কখনও সুস্পষ্ট সমাধান কার্যকর করার সাথে একটি বাগ / পার্শ্ব-প্রতিক্রিয়া থাকে। আপনি কেন অন্য কিছু সমাধানের সাথে যেতে বেছে নিয়েছেন তা নথিভুক্তকরণ পরবর্তী বিকাশকারীকে বাগটি পুনরায় উত্পাদনের থেকে বাধা দেয় যখন তারা আপনার আপাতদৃষ্টিতে দুর্বল সমাধানটি "ফিক্স" করে।
ক্যাফজিক

2
আরেকটি বিষয়, আমার প্রথম কাজ মন্তব্য হিসাবে গুরুত্বপূর্ণ হিসাবে মন্তব্য বিবেচনা। আপনি পর্যালোচনাটি পর্যালোচনা করার সময় কোডের পাশাপাশি মন্তব্যগুলি পড়ার অভ্যাসে প্রবেশ করার চেষ্টা করুন এবং যখনই সম্ভব মন্তব্যগুলি আপ টু ডেট থাকার চেষ্টা করুন। এটি মন্তব্যগুলিকে বাসি হয়ে যাওয়া এড়াতে সহায়তা করে এবং ব্যবসায়ের নিয়ম ইত্যাদি আপনার কোডে নথিবদ্ধ করে রাখে আপ টু ডেট।
এরিক হাইড্রিক

10

আপনার রবার্ট সি মার্টিনের ক্লিন কোড বইটি পড়া উচিত । এটি দুর্দান্তভাবে ব্যাখ্যা করেছে যে আপনার যদি মন্তব্যগুলির প্রয়োজন হয় তবে সম্ভবত আপনি সঠিকভাবে কোডিং করছেন না। আদর্শভাবে, আপনার কোডটি "স্ব মন্তব্য" হওয়া উচিত। ক্লিন কোডার বইটি এটি কীভাবে করা যায় তা ব্যাখ্যা করে, যাতে মন্তব্যগুলি প্রয়োজনীয় না হয় এবং যেখানে এটি প্রয়োজনীয় সেখানে মন্তব্যগুলি কীভাবে করা যায় তা ভালভাবে বর্ণনা করা হয়েছে। (যেমন একটি জটিল গাণিতিক সূত্র ব্যাখ্যা হিসাবে)


যদিও আমি এতটা জটিল গাণিতিক সূত্রটি ব্যাখ্যা করতে চাইনি যেহেতু আমি এটি সঠিক গাণিতিক স্বরলিপিতে (সম্ভবত টেক্স) লিখিতভাবে লিখতে চাই , এর তাত্পর্য এবং উত্সের ব্যাখ্যা দিয়ে। আপনি যদি সূত্রটি বুঝতে না পারেন তবে আপনার যে কোডটি কোনওভাবেই মূল্য নির্ধারণের জন্য এটি ব্যবহার করা কোডের সাথে বিশৃঙ্খলা সৃষ্টি করা উচিত নয়, যেহেতু আপনি সম্ভবত বাগ স্ক্রুটি প্রবর্তন এবং সূক্ষ্ম করতে পারেন না।
একটি সিভিএন

কোড কেবল কীভাবে , কেন বা কেন নয় তা বলতে পারে । তার জন্য আপনার মন্তব্য দরকার।

7

কোড কমপ্লিট, যেমনটি উল্লেখ করা হয়েছে, মন্তব্য লেখার বিষয়ে বিভিন্ন নির্দেশিকা রয়েছে। সংক্ষেপে, এটি পিডিএল এবং এর সংক্ষিপ্তসারটি দেওয়া যেতে পারে:

  1. কোড কী করছে তা নয়, আপনার অভিপ্রায় বর্ণনা করুন। আপনি কিছু কৌশল ব্যবহার না করে বা কাস্টম-বাস্তবায়ন ব্যবহার না করা পর্যন্ত বাস্তবায়নের বিশদটি বর্ণনা করা থেকে বিরত থাকুন। উদাহরণস্বরূপ, বিভাজনে বিটগুলি স্থানান্তরিত করা, শ্রেণীর সদস্যদের অ্যাক্সেসের জন্য পয়েন্টার পাটিগণিত ব্যবহার করা বা কিছু পুলযুক্ত বস্তুর জন্য একটি কাস্টম মেমরি বরাদ্দকারী ব্যবহার করা using

  2. প্রথমে সিউডো কোডটি লিখুন (অর্থাত্ মন্তব্যগুলি), তারপরে আপনার রুটিন / পদ্ধতি / কার্যকারিতা বর্ণনা শেষ করার পরে রিয়েল কোডে লিখুন in ব্যবহৃত ভাষা উচ্চ-স্তরের তবু সুনির্দিষ্ট, সুতরাং এটি বরং ভার্বোজ হতে পারে

  3. কোডটি লেখার আগেই আপনার কোডটি কী করছে সে সম্পর্কে ধারণা দিন

  4. আসল কোড হিসাবে কাছাকাছি মতামত আছে

লক্ষ্যটি হ'ল লম্বা বাতাসহীন সম্পর্কযুক্ত মন্তব্যগুলি এড়িয়ে যাওয়া that উচ্চ স্তরের সিউডো কোড ব্যবহার করা কার্যকরভাবে লেখার আগে আপনার চিন্তাভাবনা পরিষ্কার করতে সহায়তা করে।

গেমডেভ.টনে একটি লিঙ্ক আছে [যা পিডিএল ব্যাখ্যা করে] [১], আপনি যদি বইটি সন্ধান করতে না চান তবে।


5
প্রথমে সিউডো কোডটি লিখুন (অর্থাত্ মন্তব্যগুলি) । আমি এর চেয়ে বেশি একমত হতে পারি না মন্তব্যগুলি কোডের সাথে মেলে না তা নিশ্চিত করার আরও ভাল কোনও উপায় নেই। নতুন কোডার (এবং অনুরোধকারী বিশেষত একটি প্রাথমিক নির্দেশিকার জন্য জিজ্ঞাসা করেছেন) তাদের সাথে খুশি হওয়ার আগে একশ বার হ্যাক করবে এবং রিফ্যাক্টর ফাংশন করবে, কোডটি দ্রুত চারপাশে সরিয়ে নেওয়া হবে, পুনরায় লিখিত হবে, পুনরায় উদ্দেশ্যযুক্ত হবে এবং শেষে, তারা একটি মার্জিত কাজের সমাধান আছে, তবে এটি তাদের প্রাথমিক সিউডো কোডের মতো কিছুই দেখবে না look কোডগুলি কাজ করার সাথে সাথে কী মন্তব্যগুলি সরানো এবং আপডেট হবে? আপনি আপনার মিষ্টি বাইপিকে বাজি ধরতে পারেন তারা তা করবে না। আমার দুই সেন্ট.
বাইনারি ওয়ারিয়ার

1
এছাড়াও, সিউডো কোড মন্তব্যগুলি আপনাকে কোডটি কী করার কথা বলে তা বলে দেবে। কোডটি আপনাকে তা বলা উচিত। সিউডো কোডটি কোডটি কেন এটি করছে তা আপনাকে বলবে না। -1 ডুড, দুঃখিত, তবে আমি দ্বিতীয় দফার সাথে একমত হতে পারি না, সময় বদলেছে।
বাইনারি ওয়ারিয়ার

1
তর্ক করার জন্য নয়, আরও ব্যাখ্যা - সিউডো কোডটি আপনার লেখা কোডটির উদ্দেশ্য ব্যাখ্যা করা। অর্থ, মন্তব্য বাস্তবায়নের বিশদ সম্পর্কে নয় (যেমন "স্ট্যাকের শীর্ষে এক্স যোগ করুন") বরং কোডটি কী করার কথা রয়েছে সে সম্পর্কে নয় (যেমন "উইন্ডোটি অন্য সমস্ত কিছুর সামনে উপস্থিত করুন")। আপনি যেমনটি যথাযথভাবে উল্লেখ করেছেন, আপনাকে কোড সহ মন্তব্যগুলি সরানো দরকার। কোডটির সাথে আমি একমত নই আপনাকে জানাতে পারে কোডটি কী করছে - সর্বদা। এমনকি যদি, একটি সহায়ক / সঠিক মন্তব্য (যদি আমি এটি ভাল করে লিখতে পারি তবে!) অনেক বেশি এগিয়ে যায়। শেষ পর্যন্ত, এখনও আইএমএইচও।
এক্সট্রাাকুন

3
নামক একটি পদ্ধতি বা ফাংশন showWindowOnTop(window)সর্বদা একই প্রকৃতির মন্তব্যের চেয়ে ভাল হবে, এগুলি সবই পুরানো এবং খারাপ পরামর্শ ২০১২ সালে) পরীক্ষাগুলি আপনাকে লেখার আগে কোডটি কী করণীয় তা বোঝায়, 4) নামযুক্ত কোডটি খারাপ নামযুক্ত কোডের সাথে মেলে না এমন মন্তব্যের চেয়ে ভাল নামযুক্ত কোডটি ভাল

6

আমি কেবল একটি সাধারণ এবং সাধারণ নীতি অনুসরণ করি: আপনার মন্তব্যে কোনও কোড কী করছে তা বলা উচিত নয়, তবে এটি কেন করছে। মার্টিন ফওলারের আর্টিকেল অ্যান্ড বুক অন রি-ফ্যাক্টরিং এবং কোড কমপ্লিট বইয়ের প্রচুর পরিমাণে তথ্য রয়েছে তবে দুঃখজনকভাবে এটি আমার জ্ঞানের সংক্ষিপ্ত আকারে নয়।


1

আমার পরামর্শটি হ'ল কোনও মন্তব্য ছাড়াই কিছু কোড লিখুন এবং তারপরে এখান থেকে দূরে চলে যান। এক বছরে এটিতে ফিরে এসে পড়ুন। আপনি যে অংশটি সহজেই বুঝতে পারবেন না তা হ'ল অংশটি আপনার মন্তব্য করা উচিত।


1
হ্যাঁ, হ্যাঁ ;-) এটি বিশেষভাবে সহায়ক পরামর্শ নয়, যদিও - সম্ভবত এটির কোনও মন্তব্য হওয়া উচিত ছিল?
ক্যামেরন

যে অংশটি আপনি বুঝতে পারছেন না তার নামটি আরও ভাল নামকরণ করা উচিত। মন্তব্যগুলিকে কোডে রাখার মূল কারণ হ'ল ফাংশন / পদ্ধতিগুলি দীর্ঘতর হওয়া এবং এটি অনেকগুলি স্ব স্ব ডকুমেন্টিং টুকরো হওয়া উচিত।

0

আমি সত্যিই পছন্দ করি ইভান টড কীভাবে একমাত্র দরকারী মন্তব্য বিভাগে ( তার ব্লগ থেকে উদ্ধৃত ) তার দৃষ্টিভঙ্গির সংক্ষিপ্ত বিবরণ দেয় :

  • কমেন্টের পরিবর্তে কেন, তার চেয়ে বেশি ব্যাখ্যা করা হয়েছে। এগুলি সবচেয়ে কার্যকর।
  • নীচের বিশালাকার কোডটি কী করে তা বোঝাতে কয়েক শব্দের সাথে মন্তব্যসমূহ। এগুলি নেভিগেশন এবং পড়ার জন্য দরকারী।
  • প্রতিটি ক্ষেত্রের অর্থ কী তা ব্যাখ্যা করে একটি ডেটা কাঠামোর ঘোষণায় মন্তব্যসমূহ। এগুলি প্রায়শই অপ্রয়োজনীয়, তবে কখনও কখনও স্মৃতিতে স্বজ্ঞাতভাবে কোনও ধারণা মানচিত্র করা সম্ভব হয় না এবং ম্যাপিংয়ের বিবরণ দেওয়ার জন্য মন্তব্যগুলি প্রয়োজনীয়।
আমাদের সাইট ব্যবহার করে, আপনি স্বীকার করেছেন যে আপনি আমাদের কুকি নীতি এবং গোপনীয়তা নীতিটি পড়েছেন এবং বুঝতে পেরেছেন ।
Licensed under cc by-sa 3.0 with attribution required.