এক্সএমএল ডকুমেন্টেশন মন্তব্যে আমার কী অন্তর্ভুক্ত করা উচিত?

Question

আমি আমার কোডটি আরও ভাল করে ডকুমেন্ট করার চেষ্টা করছি, বিশেষত যখন ক্লাস সদস্যদের উপর এক্সএমএলের মন্তব্যে আসে তবে প্রায়ই এটি কেবল নির্বোধ বোধ করে।

ইভেন্ট হ্যান্ডলারের ক্ষেত্রে, নামকরণের কনভেনশন এবং পরামিতিগুলি স্ট্যান্ডার্ড এবং স্পষ্ট:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

আমার প্রায়শই সাধারণ বৈশিষ্ট্যও রয়েছে যা (আইএমও) পরিষ্কারভাবে নামকরণ করা হয় যাতে সারাংশটি অপ্রয়োজনীয় হয়:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

আমি মনে করি না যে এই জাতীয় মন্তব্যগুলি এমন কোনও তথ্য যুক্ত করে না যা ঘোষণা নিজেই ইতিমধ্যে প্রকাশ করে না। সাধারণ জ্ঞান বলে মনে হয় যে কোডটি পুনরাবৃত্তি করে এমন মন্তব্যটি উত্তম লিখিতভাবে বামে রয়েছে।

স্পষ্টতই, এক্সএমএল ডকুমেন্টেশনগুলি কেবল নিয়মিত ইনলাইন কোড মন্তব্যগুলির চেয়ে বেশি এবং আদর্শভাবে 100% কভারেজ থাকবে। এ জাতীয় ক্ষেত্রে আমার কী লেখা উচিত ? যদি এই উদাহরণগুলি ঠিক থাকে তবে তারা কোন মান যুক্ত করবে যে আমি এখন প্রশংসা করব না?

Comments

"এবং আদর্শভাবে 100% কভারেজ থাকবে" - এটি অত্যন্ত বিতর্কযোগ্য। আমি কেবলমাত্র ইন্টেলিজেন্স পপআপগুলির জন্য একটি টাইপের পাবলিক ইন্টারফেসের জন্য তাদের পছন্দ করি তবে ব্যক্তিগত পদ্ধতিগুলির জন্য তারা কেবল ভার্জিক আইএমও হয়

— এড এস।

100% কভারেজ ব্যক্তিগত পদ্ধতিগুলিতে প্রযোজ্য নয়, বিশেষত ইভেন্ট হ্যান্ডলারের ক্ষেত্রে।

— এসএলএক্স

ঘোস্টডক আমার জন্য আমার ডকুমেন্টেশন লেখেন। "আপনি GetData()কি" জিজ্ঞাসা করেন? কেন, Gets the dataঅবশ্যই!

— ডেভিন বার্ক

@ জাস্টিন: ঘোস্টডক দেখতে খুব সুন্দর লাগছে। আমি এটি নিতে পারে।

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

— কিথ

Answer 1

এক্সএমএল ডক মন্তব্যগুলি জনসাধারণের সদস্যদের জন্য তৈরি।

কম্পাইলার সতর্কবার্তা পরিষ্কারভাবে এই বলে:

সর্বজনীনভাবে দৃশ্যমান প্রকার বা সদস্য 'টাইপ_ম_মেম্বার' এর জন্য এক্সএমএল মন্তব্য অনুপস্থিত

আপনি যদি কেবল সদস্যদের নাম থেকে ইতিমধ্যে সুস্পষ্ট না হন তবে আপনার কেবলমাত্র ব্যক্তিগত সদস্যদের এক্সএমএল মন্তব্যগুলি যুক্ত করা উচিত।

Answer 2

খাঁটি মতামত এখানে, সুতরাং এটির জন্য এটি গ্রহণ করুন।

আমি অতিরিক্ত অতিরিক্ত এক্সএমএল মন্তব্য ঘৃণা করি । সম্ভবত ভূত ডক শৈলীর জন্য যা পদ্ধতি / সম্পত্তির নামে খালি স্থান যুক্ত করে। এটি কোনও মূল্য যুক্ত করে না এবং আসল কোড সম্পর্কে আমার দৃষ্টিভঙ্গিটিকে কেবল ছড়িয়ে দেয়।

কোনও কিছুর যদি স্পষ্টকরণ প্রয়োজন হয় তবে তা সর্বদা মন্তব্য করুন। তবে অর্থপূর্ণ নাম সহ ছোট ফোকাসযুক্ত পদ্ধতি দ্বারা প্রচুর স্পষ্টতা জানানো যেতে পারে। আপনি কোডটি উন্নত করতে এবং মন্তব্যটিকে অপ্রয়োজনীয় করতে পারলে মন্তব্য মন্তব্য করবেন না।

এমনকি পেতে আমার অপ্রয়োজনীয় ব্যবহার শুরু না this.এবং Me.।

পার্শ্ব নোট হিসাবে, আমি একটি ভিজ্যুয়াল স্টুডিও অ্যাডিন রাখতে পছন্দ করব যা আমাকে এক্সএমএল মন্তব্যের দৃশ্যমানতা টগল করতে দেয়। (ইঙ্গিত ইঙ্গিত)

Comments

আমি অনুমান করব যে this.জিনিসটি শুরু হয়েছে কারণ কোনও কারণে মাইক্রোসফ্টের অফিসিয়াল গাইডলাইনগুলি স্থানীয় ভেরিয়েবল এবং উদাহরণ privateভেরিয়েবলগুলির জন্য ঠিক একই নামকরণ কনভেনশনটি ব্যবহার করার পরামর্শ দিয়েছে । এটি একটি মারাত্মক ত্রুটিযুক্ত স্টাইল, আইএমও - কিছু ক্ষেত্রে আপনি StackOverflowExceptionসম্পত্তি থেকে একটি চর্বিযুক্ত আঙুলের দূরে থাকেন setবা MyProperty = MyProperty;কোনও ক্ষেত্রকে কনস্ট্রাক্টর প্যারামিটারের পরিবর্তে শূন্যে শুরু করতে পারেন এবং এমনকি মাইক্রোসফ্ট m_বেশিরভাগ সময় অভ্যন্তরীণভাবে ব্যবহার করতে থাকে ।

— jrh

Answer 3

কোনও জন সদস্যের উপর এক্সএমএল ডকুমেন্টগুলি মোটামুটি ভার্বোজ এবং সম্পূর্ণ হওয়া উচিত, যেমনটি @ এসএলক্স উল্লেখ করেছেন।

তবে এগুলি প্রাইভেট, সুরক্ষিত বা অভ্যন্তরীণ সদস্যদের জন্যও সত্যই কার্যকর হতে পারে কারণ ভিজ্যুয়াল স্টুডিও এক্সএমএল ডকের মন্তব্যে ইন্টেলিজেন্সকে সাহায্য করবে এবং টুলটিপগুলিকে সহায়তা করবে।

এই যে মানে:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

পুরোপুরি পর্যাপ্ত ডকুমেন্টেশন হতে পারে তবে:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

আপনার কোডের অন্য কোথাও থেকে দ্রুত দেখতে খুব সহজ হবে।

সাধারণত জনসাধারণের এক্সএমএল মন্তব্যে আমি এপিআই-র কিছু বাহ্যিক ব্যবহারকারীর জন্য লিখছি, এবং অভ্যন্তরীণ এক্সএমএল মন্তব্যে আমি আমার বা আমার দলের অন্যদের জন্য লিখছি।

প্যারামিটারের বিবরণগুলি এড়িয়ে যাওয়া সম্ভবত পূর্বের এবং খারাপদের জন্য একটি খারাপ ধারণা।

আমি যুক্ত করব (বিশেষত পাবলিক এপিআই ডক্সে) সর্বদা অন্তর্ভুক্ত থাকব বৈশিষ্ট্যগুলিতে getবা না set:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

এটি সি # এর ইন্টেলিজেন্স থেকে স্পষ্ট নয় যেটি পাওয়া যায় getবা setনা, তবে এটি এক্সএমএল মন্তব্যে রাখার অর্থ আপনি টুলটিপ থেকে এক নজরে বলতে পারবেন।

Comments

নির্ভর করে। সম্পত্তি হিসাবে আপনার যদি একটি ছাড়া public getআর কী থাকে internal set? কীভাবে মন্তব্য করবেন? :-)

— Guillaume,

@ গুইলিউম যেহেতু এক্সএমএল মন্তব্যগুলি সর্বজনীন তাই আমি এক্সএমএল-এ কেবলমাত্র ডকুমেন্টিং দিয়ে যাই getএবং setনিয়মিত //মন্তব্য সহ নথিটি নথিভুক্ত করি ।

— কিথ