কোনও পদ্ধতির স্বাক্ষরে প্রত্যেকটি প্যারামিটারের জন্য জাভাদোক মন্তব্য লেখার প্রয়োজন কি?

Question

আমার দলের একজন ডেভস বিশ্বাস করেন যে কোনও পদ্ধতির স্বাক্ষরে প্রত্যেকটি প্যারামিটারের জন্য জাভাদোক মন্তব্য লিখতে হবে। আমি এটি প্রয়োজনীয় বলে মনে করি না এবং বাস্তবে আমি এটি ক্ষতিকারকও হতে পারি বলে মনে করি।

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

তবে আমি মনে করি এটি প্রতিটি প্যারামিটারের জন্য করা অপ্রয়োজনীয়। যদি প্যারামিটারটির জন্য এটি ইতিমধ্যে সুস্পষ্ট হয় তবে জাভাদোক মন্তব্য অপ্রয়োজনীয়; আপনি কেবল নিজের জন্য অতিরিক্ত কাজ তৈরি করছেন। তদুপরি, আপনি যে কেউ আপনার কোড বজায় রাখতে হয় তার জন্য অতিরিক্ত কাজ তৈরি করছেন। সময়ের সাথে সাথে পদ্ধতিগুলি পরিবর্তন হয় এবং মন্তব্যগুলি বজায় রাখা আপনার কোড বজায় রাখার মতোই গুরুত্বপূর্ণ is আপনি "জেড কারণে X এর জন্য X" এর মতো মন্তব্যটি কতবার দেখেছেন তা দেখতে কেবল মন্তব্যটি পুরানো হয়ে গেছে, এবং বাস্তবে পদ্ধতিটি আর এক্স প্যারামিটারটি নেয় না? এটি সর্বদা ঘটে, কারণ লোকেরা মন্তব্য আপডেট করতে ভুলে যায়। আমি যুক্তি দিয়ে বলব যে একটি বিভ্রান্তিকর মন্তব্য মোটেও কমেন্টের চেয়ে বেশি ক্ষতিকারক। এবং এইভাবে অতিরিক্ত মন্তব্য করার বিপদ: অপ্রয়োজনীয় ডকুমেন্টেশন তৈরি করে আপনি '

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

Comments

অনেক জাভা আইডিই (বিশেষত ইন্টেলিজ) নিখোঁজ জাভাদোক প্যারামিটারকে একটি ডকুমেন্টেশন সতর্কতা হিসাবে ট্যাগ করবে

— গ্যারি

নেটবিয়ানস এবং ইক্লিপসও করবে।

— Žদ্রো

Answer 1

জাভাডোক (এবং, মাইক্রোসফ্ট শব্দে, এক্সএমএলডোক) টিকা মন্তব্য নয় , সেগুলি ডকুমেন্টেশন ।

মন্তব্যগুলি যতটা বিচ্ছিন্ন হতে পারে আপনি যেমন তা চান তেমন; আপনার কোডটি অর্ধেকটা পঠনযোগ্য বলে ধরে নিচ্ছেন, তবে সাধারণ মন্তব্যগুলি ভবিষ্যতের বিকাশকারীদের কোডটি বোঝার / বজায় রাখতে সহায়তা করার জন্য কেবল সাইনপোস্ট যা তারা ইতিমধ্যে দু'ঘন্টার জন্য পর্যবেক্ষণ করেছে।

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

আর্গুমেন্ট / প্যারামিটারের নামগুলি কখনই স্ব-ব্যাখ্যামূলক হয় না । আপনি সর্বদা মনে করেন যে আপনি কোডটি নিয়ে কাজ করার জন্য গত দিনটি কাটিয়েছিলেন তবে 2 সপ্তাহের ছুটির পরে এটিতে ফিরে আসার চেষ্টা করুন এবং তারা দেখতে পাবেন যে তারা আসলেই কতটা অসহায়।

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

Comments

+1: এটি কোডের মতোই প্রয়োজনীয়। এটিতে ভাল স্বয়ংক্রিয় পরীক্ষা নেই।

— এস। লট

যদি কোনও পদ্ধতির প্যারামিটারগুলিতে উদাহরণস্বরূপ এক্স এবং ওয়াই সমন্বয়গুলির তিনটি জোড়া অন্তর্ভুক্ত থাকে যা সমান্তরালীর সংলগ্ন কোণ হিসাবে ব্যাখ্যা করা হয়, তবে প্রতিটি প্যারামিটারের জন্য একটি করে ছয়টি ছোট ডকুমেন্টস, বা পংক্তির উদ্দেশ্য বর্ণনা করার জন্য আরও দরকারী? সমান্তরালগ্রাম (x1, y1), (x2, y2), (x3, y3), এবং (x1 + x3-x2, y1 + y3-y2) এর ক্ষেত্রে পদ্ধতি [পরবর্তীকালের বিপরীতে (x2, y2)]? পদ্ধতির উদ্দেশ্যটি যদি প্যারামিটারের নামগুলির ক্ষেত্রে সংজ্ঞায়িত করা হয়, তবে আমি পরামিতিগুলি সম্পর্কে অতিরিক্ত ডকুমেন্টেশন অনেক ক্ষেত্রে অতিরিক্ত অতিরিক্ত প্রয়োজন বলে মনে করব।

— সুপারক্যাট

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

— অ্যারোনআউট

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

— সুপারক্যাট

... ধনুর্বন্ধনীগুলিতে মানগুলি আবদ্ধ করা, তবে এটি উভয়ই পারফরম্যান্স এবং পাঠযোগ্যতার অবস্থান থেকে ভাল হতে পারে। জাভা তেমন কোনও ধারণা নেই; একটি জেভিএম-ভিত্তিক ভাষা প্যারামিটারগুলির জন্য দক্ষতার সাথে এমন কোনও জিনিসকে সমর্থন Point p1করতে পারে (একটি প্যারামিটারটি অনুবাদ করা যেতে পারে int p1_x, int p1_y), তবে জেভিএমের কোনও ফাংশন এ জাতীয় জিনিস ফেরত দেওয়ার জন্য কোনও কার্যকর ব্যবস্থা নেই।

— সুপারক্যাট

Answer 2

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

মনে রাখবেন: এমন কিছু যা আপনার কাছে বোঝার মতো তা অন্য কারও দ্বারা সম্পূর্ণরূপে ব্যাখ্যা করা যেতে পারে, আপনি যতই জাগতিক মনে করেন না কেন (যিনি ইংরেজীতে এতটা শক্তিশালী নন যে আপনার কোডটি পড়ে বোঝার চেষ্টা করছেন) think

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

Answer 3

আসুন এই ধারণা থেকে শুরু করা যাক যে বিকাশকারী চক্রগুলি সেই সংস্থান যা আমরা সংরক্ষণের চেষ্টা করছি।

সুতরাং এর অর্থ হ'ল ডেভস-এর স্ব-স্পষ্ট প্যারামিটারগুলি এবং ডান ফেরতের মানগুলি নথিভুক্ত করা উচিত নয়?

ঠিক আছে, এটি ভেঙে দিন।

যদি আমরা সমস্ত কিছু নথিভুক্ত করি তবে ধরে নেওয়া যে প্রান্তিক মন্তব্যগুলি সত্যিই তুচ্ছ এবং কোনও চিন্তা বা গবেষণার প্রয়োজন নেই, ব্যয়টি আসলে মন্তব্যটি টাইপ করতে এবং টাইপগুলি ঠিক করার জন্য যুক্ত সময়।

যদি আমরা বাছাই এবং চয়ন করি, তবে ব্যয়গুলি হ'ল:

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

সুতরাং, আমি কেবল সবকিছু নথিভুক্ত করতে ঝোঁক হবে। অবক্ষয়টি সুনির্দিষ্ট, তবে এতে রয়েছে।

Answer 4

যদি আপনি জাভাদোকটি যাইহোক লিখছেন তবে আপনি সম্ভবত এটি "সম্পূর্ণরূপে" পরামিতিগুলি সহ সম্পূর্ণ লিখবেন write এগুলি আপনার বা অন্য বিকাশকারীদের কাছে স্পষ্ট হতে পারে তবে নতুন যে কেউ এটিকে দেখছে তা প্রতিটি প্যারামিটারের উদ্দেশ্য জেনে উপকৃত হবে।

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

Answer 5

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

Comments

"ক - যুক্তি যার পরম মান নির্ধারণ করা উচিত" ম্যাথ.এবস এর ডকুমেন্টেশনে সত্যিই কিছু যুক্ত করে?

— কেভিন cline

@ কেভিন স্লাইন চিন্তাভাবনা করার জন্য কার্যকর হতে পারে ;-)

— গ্যারি

Answer 6

'প্রয়োজনীয়' সম্পূর্ণরূপে বিষয়গত। আমি মনে করি আপনি যা জিজ্ঞাসা করছেন তা হ'ল 'আপনার পরিস্থিতিতে আপনার কি জাভাদোক মন্তব্য যুক্ত করা উচিত '। আপনার অ্যাপ্লিকেশনটির সুযোগ বা প্রসঙ্গটি না জেনে, আপনার জন্য কী উপযুক্ত তা আমরা কীভাবে জানতে পারি?

যদি এই সর্বজনীন ফেসিং কোড (যেমন, কোডগুলি অন্যদের অ্যাক্সেসের জন্য যেমন একটি এপিআই বোঝায়) বোঝায় তবে হ্যাঁ, প্রতিটি একক প্যারামিটার নথি করুন। অনুমান করবেন না যে পাঠক আপনার মতো প্রজেক্টটি সম্পর্কে জানেন। তবে অন্যথায়, আপনার নিজের সিদ্ধান্ত নেওয়ার বিষয়টি আপনার এবং আপনার দলের উপর নির্ভর করে।

Comments

আমি দেখতে পাচ্ছি যে এটি জনসাধারণের মুখোমুখি না হওয়া সত্ত্বেও, কয়েক বছর পরে আমি যদি এটির দিকে ফিরে তাকাই তবে এটি আমাকে আমার নিজের কোডটি বুঝতে সাহায্য করে : পি

— ডেমিয়ান ব্রেচেট

এই পদ্ধতির পরিচিতিটি "হেক আমরা নতুন লোকটিকে আমরা চলে যাওয়ার পরে 4 বছরের মধ্যে জঘন্য কোডটি পড়তে করব" নামেও পরিচিত। কাছে।

— টিম উইলিসক্রফ্ট