মন্তব্য / ইন-কোড ডকুমেন্টেশন স্টাইলগুলি

Question

এটি একটি মূ .় প্রশ্ন হতে পারে, তবে এটি আমার মাথার পিছনে কিছুক্ষণ হয়ে গেছে এবং আমি কোথাও এর সদুত্তর খুঁজে পাই না।

আমার একজন শিক্ষক আছেন যিনি বলেছেন যে আমাদের প্রতিটি পরামিতি একটি বর্ণনার সাথে স্পষ্টভাবে তালিকাভুক্ত করা উচিত, এমনকি সেখানে কেবলমাত্র একটি রয়েছে। এটি প্রচুর পুনরাবৃত্তি করে:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

ইন-কোড ডকুমেন্টেশন লেখার সময়, আপনি কতটা বিস্তারিত?

Comments

আপনার উদাহরণ সরল। অনুশীলনে, আপনি কেবলমাত্র প্যারামিটারের প্রকারের চেয়ে অনেক বেশি সীমাবদ্ধতা নির্দিষ্ট করতে পারেন, যদি এটি কোনও পূর্ববর্তী হয় তবে এটি অবশ্যই পূর্ণসংখ্যা হতে হবে যা X এবং Y এর মান হয় If , এবং এটি কী কী মান হতে পারে (কোনও ফাংশন উপস্থিত থাকতে পারে যা হুবহু 1.01, 2.31 এবং 5.01 প্রদান করে!)। আরও সুনির্দিষ্ট হন এবং আপনি যতটা পুনরাবৃত্তি দেখতে পাবেন না ...

— পুরাতন অ্যাকাউন্ট

Answer 1

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

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

---

^{1: ভাষাটির সাথে পরিচিত অন্য কেউ কোডটিতে লেখা আছে teach শিক্ষার জন্য মন্তব্যগুলি লেখবেন না, তথ্য পরিপূরক করতে মন্তব্য করবেন না।}

Comments

+1, তবে নিশ্চিত হয়ে নিন যে আপনি মনে রেখেছেন যা আপনার কাছে যা স্পষ্ট তা অন্য কোনও প্রোগ্রামারের কাছে স্পষ্ট নাও হতে পারে।

— জোশ কে

@ জোশ: ভাল কথা, তাই আমি উত্তরটি সম্পাদনা করেছি।

— ল্যারি কোলেম্যান

@ ল্যারি: ভাল মন্তব্যেও কী অন্তর্ভুক্ত করা উচিত: কীটি প্রবেশ করে, কী বাইরে আসে এবং বিশেষত কোন ধরণের ভিতরে এবং বাইরে যায়।

— জোরিস মাইস

@ জোরিস: কী প্রবেশ করে এবং কী বাইরে যায় তা "ইনপুট সম্পর্কে প্রত্যাশা" এবং "কোডটি কীভাবে আচরণ করবে" দ্বারা আচ্ছাদিত। কোন ধরণের এবং বাইরে চলে যায়, আমি আগে যা বলেছিলাম তার সাথে আমি দাঁড়িয়ে আছি: "ভাল মন্তব্যে কোডের মধ্যে পুনরাবৃত্তি হয় না।"

— ল্যারি কোলেম্যান

@ ল্যারি: আমি প্রতিবার কোনও ফাংশন পুনরায় ব্যবহার করতে চাইলে ঘোষণাগুলি এবং কোডটি পেরিয়ে যাওয়ার চেয়ে আমি মন্তব্যটিতে পড়েছি। শৈলীর বিষয়টি আমার ধারণা, আমি খুব অলস লোক।

— জোরিস মেয়েস

Answer 2

বেশ কয়েকটি ভাষায় এপিআই নথি তৈরির বৈশিষ্ট্য রয়েছে যেমন রুবি, জাভা, সি # এবং সি ++ (একটি কমান্ড লাইন সরঞ্জামের মাধ্যমে)। আপনি যখন সেভাবে এটি সম্পর্কে ভাবেন তখন এটি API ডক্স লেখাকে আরও গুরুত্বপূর্ণ করে তোলে। সর্বোপরি, এটি "আমি কীভাবে করব ...?" প্রশ্নের উত্তর দেয় সুতরাং আমি পুনরাবৃত্ত হওয়ার মতো কিছু করব না Function: MyFunctionযখন ফাংশনের নামটি সবার দেখার জন্য প্লেইন থাকে। এপিআই ডক জেনারেশন সরঞ্জামগুলি আমার পক্ষে এটি করার জন্য যথেষ্ট স্মার্ট। তবে, নিম্নলিখিত বিবরণগুলি বিশেষত জনসাধারণের পদ্ধতি / ফাংশনগুলিতে দরকারী:

• সংক্ষিপ্তসার (এটি কী করে এবং কীভাবে এটি ব্যবহার করতে হবে তার একটি সংক্ষিপ্তসার)
• পরামিতিগুলির তালিকা এবং কী প্রত্যাশিত
• রিটার্নের মান (আউটপুট) কী হবে
• কোনও ব্যতিক্রম যা স্পষ্টভাবে এবং কেন নিক্ষেপ করা যায়

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

যদি এই বৈশিষ্ট্যগুলি ব্যতীত কোনও ভাষা হয় তবে মন্তব্যগুলি সহায়তা করে তবে প্রায় ততটা নয়।

Comments

যদি আউটপুট বিবরণটির সংক্ষিপ্তসারটি অন্তর্ভুক্ত করা হয় তবে তা গ্রহণযোগ্য? উদাহরণস্বরূপ, Returns the square root of Xফেরতের মান কী তাও বর্ণনা করে।

— ম্যাক্সপাম

হ্যাঁ; শিক্ষার্থীদের যা শেখানো উচিত তা হ'ল এই ডকুমেন্টেশন বৈশিষ্ট্যগুলি ব্যবহার করা।

— জেরেমি

আমি সম্ভব হলে লজিক্যাল অ্যাবস্ট্রাকশনটিতে এপিআই ডক্স আরও রাখতে চাই। উদাহরণস্বরূপ, Returns the color for this rayবা Returns the requested Message, or null if it can't be found। তবে হ্যাঁ, সংক্ষিপ্তসারটি হ'ল এপিআই ডক্সের মাংস।

— বারিন লরিটস

Answer 3

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

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

এখন থেকে 3 মাস সকালে সকাল 3 টায় পরার জন্য নিজেকে স্বল্প ভাবি। প্যারামিটার (বুলিয়ান পতাকা) কী বোঝায় তার বিপরীতে আপনি আপনার দুর্দান্ত পাবলিক ডক্সের জন্য নিজেকে ধন্যবাদ জানাবেন ...

Comments

কখনও কখনও ফাংশনগুলিতে কর্নার-কেস আচরণ থাকতে পারে যা আলগোরিদম বলতে বোঝায় তার থেকে পৃথক। উদাহরণস্বরূপ, float0.5 টি যোগ করে কোনও পূর্ণসংখ্যার সাথে গোল করে ফলাফলের তলটি নেওয়া নীচের সবচেয়ে বড় কারণ হতে পারেfloat 0.5 এর বড়টি ভুলভাবে গোল হয়ে যায়। এই ক্ষেত্রে, কখনও কখনও এটি আলাদা করা গুরুত্বপূর্ণ হতে পারে যে কোনও ফাংশনটি নিকটতম পূর্ণসংখ্যার (অথবা পরবর্তী দুটি উচ্চ মানের যখন সামঞ্জস্যপূর্ণ হয় তখন পরবর্তী উচ্চতর পূর্ণসংখ্যার) হিসাবে সংজ্ঞায়িত করা উচিত, বা 0.5 (সম্ভবত একটি অন্তর্বর্তী বৃত্তাকার পদক্ষেপের সাথে) সংযুক্ত করা এবং ফলাফল মেঝে গ্রহণ।

— সুপারক্যাট

Answer 4

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

জাভা থেকে, আইডিই দ্বারা স্বয়ংক্রিয়ভাবে উত্পাদিত:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

অন্তর্নির্মিত ভাষা বৈশিষ্ট্যগুলির জন্য ডকুমেন্টেশন তৈরি করতে এটি একই ফর্ম্যাটটি ব্যবহৃত হয় - উদাহরণ: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

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

আমি প্রায়শই কিছুটা অপ্রয়োজনীয় দেখতে পাই সেই বিটটি হ'ল - সাধারণত এটি আমার পদ্ধতির বর্ণনার সাথে প্রায় একই।

Answer 5

মন্তব্যের জন্য দুটি উদ্দেশ্য রয়েছে:

1. আপনি কয়েক মাস / বছর পরে ফিরে এলে আপনার কোড কী করে তা আপনাকে দ্রুত তা মনে করিয়ে দেওয়ার জন্য পরিবেশন করে। এইভাবে আপনাকে আপনার স্মৃতি সতেজ করতে আপনার কোডটি পুনরায় পড়তে হবে এবং বিশ্লেষণ করতে হবে না।
2. তারা অন্যদের সাথে রিলে করে যারা আপনার কোডটি কী করছে তা আপনার কোড নিয়ে পড়া বা কাজ করা হতে পারে।

এর কাছে যাওয়ার অনেকগুলি বিভিন্ন উপায় অবশ্যই রয়েছে তবে আপনি আরও ভাল এবং সামঞ্জস্যপূর্ণ তত ভাল। কার্যকরী মন্তব্য করা কার্যকর প্রোগ্রামিংয়ের মতো শিখতে সময় নেয়। মনে রাখবেন যে স্কুলে মন্তব্যগুলির মূল বক্তব্যটি দেখার পক্ষে আপনার পক্ষে যে শক্তিশালী কাজ করা হচ্ছে তা সত্যিই এটির সত্যতা পাওয়ার পক্ষে যথেষ্ট নয় তবে তারা কেবল এটি আপনার সাথে পরিচয় করানোর চেষ্টা করছে। এবং সাধারণত যেভাবে আপনাকে এটি করতে শেখায় তা হ'ল আপনার অধ্যাপকের স্টাইলটি কোনও উপায়ে কোনও ধরণের মান নয়। আপনার জন্য কাজ করে তা বিকাশ করুন। এবং মনে রাখবেন ... একটি বোকা মন্তব্য মত একটি জিনিস আছে! :) উদাহরণ:

a += 1; //adds 1 to the value in a

সত্যি? ধন্যবাদ! হাঃ হাঃ হাঃ

Answer 6

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

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

এবং @ ল্যারি কোলম্যান বলেছিলেন, ইনলাইন মন্তব্যগুলিতে আপনাকে কিছু কোডের টুকরো কেন করা উচিত তা বলা উচিত।

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Answer 7

যদি এটি ডক প্রজন্মের পরিষেবাতে থাকে তবে ভারবস মন্তব্য (যদিও বিরক্ত হলেও) সম্ভবত একটি ভাল জিনিস। যদিও আপনাকে এটিকে একটি দলের লক্ষ্য করতে হবে মন্তব্যে শীর্ষে থাকতে এবং সেগুলি আপ টু ডেট রাখতে।

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

আমি বরং স্পষ্ট সংক্ষিপ্ত অন-মন্তব্য কোড আছে। বর্ণনামূলক দাবি বা পদ্ধতি সহ আমাকে কিছু পরীক্ষা দিন এবং আমি খুশি এবং অবহিত।