জাভা সমান মত সম্যক পদ্ধতি জন্য ডকুমেন্টেশন রচনা

10

সমতুল্য, তুলনামূলকভাবে ইত্যাদির মতো বহুল পরিচিত পদ্ধতির জন্য মন্তব্যগুলি লেখার পক্ষে কি একটি ভাল অনুশীলন?

নীচের কোডটি বিবেচনা করুন।

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }

আমার সংস্থার উপরের মত মন্তব্য লিখতে পাগল? উপরের জাভাদোকের মন্তব্যটি কী দরকার? সমান পদ্ধতি এবং পছন্দগুলি (তুলনা, তুলনা করুন) ইত্যাদি কী করে তা সুস্পষ্ট এবং ভালভাবে বোঝা যায় না?

আপনার পরামর্শ কি?

java comments

— বিনোথ কুমার সিএম
সূত্র

3

আপনার বর্তমান মন্তব্যটি ভুল। জেনেরিক অবজেক্ট গ্রহণের ক্ষেত্রে আপনার পদ্ধতির স্বাক্ষরটি সঠিক, তবে আপনার মন্তব্যটি 'একই ধরণের অবজেক্ট' বলে।

— সি_মেকার

4

আমি বরং এই মন্তব্যটির জন্য একটি মন্তব্য দেখতে চাই যাতে সামঞ্জস্যতা এই বিষয়টির জন্য কী বোঝায়। "সমতা" পিচ্ছিল শব্দ term কমন লিস্পে, বহু সমতা ফাংশন রয়েছে এবং আপনি যথাযথ ব্যবহারের জন্য বেছে নিন।

— ডেভিড থর্নলি

এই ক্ষেত্রে, আমি দুটি অর্থকে "অর্থবহ উপায়ে" সমান বলে উল্লেখ করছি। উদাহরণস্বরূপ, দুটি কর্মচারী বস্তু সমান হয় যদি তাদের একই বর্ণের শার্ট পরে থাকে তবে তারা একই কর্মী আইডি থাকে।

— বিনোথ কুমার সিএম

6

@ উইনোথ: "অর্থপূর্ণ উপায়" হ'ল আপনার যা ডকুমেন্ট করা দরকার :)

— সি_মেকার

6

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

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

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

— টমাস ওভেনস
সূত্র

উত্তরাধিকার সম্পর্কে আমি সচেতন তবে সংস্থাটি স্পষ্টত জাভা ডক্স লেখার জন্য "আদেশ দেয়"।

— বিনোথ কুমার সিএম

3

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

— টমাসের মালিক

@ থমাস: অনুমতি বিকল্প জিজ্ঞাসা করার চেয়ে ক্ষমা প্রার্থনা রয়েছে: চুপচাপ নিয়মগুলি বাঁকুন এবং দেখুন যে কেউ অভিযোগ করে কিনা।

— dsimcha

@dimchacha সম্ভবত, তবে যদি এটি পুনরাবৃত্তি হয় তবে এটি কাজের পক্ষে খারাপ হতে পারে। এটি কোনও এক বা দ্বিগুণ জিনিস নয়।

— থমাস Owens

9

আমার দলে আমরা সাধারণত @inheritDocটীকাটি ব্যবহার করি equals()এবং hashcode()আমি আশা করি আমরা এটি না করতাম।

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

অন্ততপক্ষে কী কী বৈশিষ্ট্যগুলি পদ্ধতিতে অংশ নিয়েছে এবং এমনকি এটি কেন তা হতে পারে তা নথিভুক্ত করা ভাল।

— c_maker
সূত্র

1

আপনার শেষ বিবৃতিটি এটিকে নিজেই দলিল করার সর্বোত্তম কারণ। এটি কি করছে তা ব্যাখ্যা করুন। অবশ্যই সমান () ক্লাসের প্রতিটি উপাদানকে তুলনা করতে পারে, বা আপনি এটি সমস্ত স্ট্রিং ক্ষেত্র বা অন্য কোনও কিছুর সাথে তুলনা করতে চাইতে পারেন।

— নিকোলাস

2

মনে রাখবেন যে মন্তব্যগুলি যদি সঠিক হয় তবে সব ধরণের বিকাশকারীকে সহায়তা করে।

সমস্যাটি হ'ল এগুলি কখনও কখনও অসম্পূর্ণ এবং সঠিক না।

2 বস্তুর সাথে তুলনা করার জন্য সত্যই জটিল হতে পারে (উদাহরণস্বরূপ 2 টি চালানের বস্তুর তুলনা করা), আপনার পদ্ধতিটি সময়ের সাথে বিকশিত হতে পারে এবং তারপরে মন্তব্য করা প্রয়োজন।

"দরকারী এবং অর্থবহ" মন্তব্যে পদ্ধতির উদ্দেশ্য, বিধিগুলি ইত্যাদি দেখানো ভাল জিনিস।

— কোন সম্ভাবনা নেই
সূত্র

2

শূন্য মন্তব্যে লিটার কোড দেওয়া অত্যন্ত চর্চা:

/**
 * This method compares the equality of the current object with the object of same type...
 */

এটি দরকারী কিছুই বলে না। সবচেয়ে খারাপ, এটি স্টাইল এবং ব্যাকরণ উভয়ই দরিদ্র:

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

পরিবর্তে, দুটি বস্তুকে সমান বিবেচনা করা হলে মন্তব্যে নির্দেশ করা উচিত। এখানে, আমি পদ্ধতিটির বিবরণ পুরোপুরি বাদ দিতে পারি এবং কেবলমাত্র রিটার্ন মানটি নথি করি, উদাহরণস্বরূপ:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

তুচ্ছ get / সেট পদ্ধতির জন্য উত্পন্ন মন্তব্যগুলি সবচেয়ে খারাপ।

— কেভিন ক্লাইন
সূত্র

1

আমাদের কোডিং স্ট্যান্ডার্ড নির্দেশ দেয় যে কোনও পদ্ধতির ওভাররাইড করার সময় এটিকে নথিভুক্ত করার দরকার নেই যতক্ষণ না ওভাররাইডিংয়ের মধ্যে, প্যারেন্ট ক্লাস বা ইন্টারফেসে ডকুমেন্টেশন সাব বা বাস্তবায়নকারী-শ্রেণীর জন্য আর সঠিক এবং বিস্তৃত না হয়।

সমানদের জন্য, আমরা লক্ষ করতে চাই যে তুলনাটি কেবলমাত্র একটি প্রাথমিক কীতে করা হয় যখন কোনও ডাটাবেস ব্যাকড সত্তার সাথে তুলনা করা হয় কারণ এটি ডকুমেন্টেশনের সাথে পুরোপুরি সামঞ্জস্যপূর্ণ নয় Object.equals()।

— কিরীচ
সূত্র

0

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

— পিটার টেলর
সূত্র

0

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

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

— বব সান্টোস
সূত্র