কোনও অভ্যন্তরীণ লাইব্রেরির জন্য ডোক্সিন মন্তব্য ব্লক কোথায় রাখবেন - এইচ বা সিপিপি ফাইলগুলিতে? [বন্ধ]

Question 1

বন্ধ । এই প্রশ্নটি মতামত ভিত্তিক । এটি বর্তমানে উত্তর গ্রহণ করছে না।

এই প্রশ্নটি উন্নত করতে চান? প্রশ্নটি আপডেট করুন যাতে পোস্টটি সম্পাদনা করে সত্য এবং উদ্ধৃতি দিয়ে উত্তর দেওয়া যায় ।

2 বছর আগে বন্ধ ।

এই প্রশ্নটি উন্নত করুন

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

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

পেশাদাররা:

হেডার ফাইলগুলিতে কম বিশৃঙ্খলা, কেবল ফাংশনগুলির শ্রেণিবদ্ধকরণ যুক্ত করা যেতে পারে।
উদাহরণস্বরূপ ইন্টেলিসেন্স ব্যবহার করা হলে মন্তব্য ব্লকগুলির সংঘর্ষ হয় না - এটি একটি ত্রুটি যা আমি পর্যবেক্ষণ করেছিলাম যখন আমার .H ফাইলে কোনও ফাংশনের জন্য মন্তব্য ব্লক থাকে এবং একই .H ফাইলটিতে এর ইনলাইন সংজ্ঞা থাকে have .INL ফাইল থেকে অন্তর্ভুক্ত।

কনস:

(স্পষ্টত এক) মন্তব্য ব্লকগুলি যেখানে ঘোষণাপত্র রয়েছে সেখানে শিরোলেখ ফাইলগুলিতে নেই।

সুতরাং, আপনি কি মনে করেন এবং সম্ভবত পরামর্শ দেন?

Question 2

কোডটি ব্যবহার করুন এবং কোডটিতে কাজ করার সাথে সাথে লোকেরা এটি পড়বে এবং লিখবে Put

ক্লাসের মন্তব্যগুলি ক্লাসের সামনে যায়, পদ্ধতিগুলির সামনে পদ্ধতিতে মন্তব্যগুলি।

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

Question 3

আমি একাধিক জায়গায় নাম নথিভুক্ত করা যেতে পারে যে সত্য ব্যবহার করতে চাই।

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

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

উদাহরণ স্বরূপ:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Question 4

শিরোনামে মন্তব্য থাকার অর্থ একটি মন্তব্য পরিবর্তিত হলে কোনও শ্রেণীর সমস্ত ব্যবহারকারীকে অবশ্যই পুনরায় কম্পাইল করতে হবে। একটি বড় প্রকল্পের জন্য, কোডাররা পরবর্তী 20 মিনিটের সবকিছু পুনর্নির্মাণে ব্যয় করতে ঝুঁকিপূর্ণ হলে তারা শিরোনামগুলিতে মন্তব্যগুলি আপডেট করার ক্ষেত্রে কম ঝুঁকবে।

এবং .. যেহেতু আপনার এইচটিএমএল ডকটি পড়ার এবং ডকুমেন্টেশনের জন্য কোডটি ব্রাউজ করার কথা নয়, তাই কোনও বড় সমস্যা নয় যে মন্তব্য ব্লকগুলি উত্স ফাইলগুলিতে সন্ধান করা আরও কঠিন।

Question 5

শিরোনাম: ফাইলগুলি দেখার সময় অন্যান্য "শব্দ" কম থাকায় মন্তব্যগুলি পড়া সহজ to

উত্স: তারপরে মন্তব্যগুলি দেখার সময় আপনার কাছে পড়ার জন্য আসল কার্যাদি রয়েছে।

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

তবে আপনি সাধারণ কমান্ডের সাহায্যে ফলাফলগুলি বিভিন্ন ফাইল ডকুমেন্টেশনে অনুলিপি করতে পারেন। যেমন: -

আমার file1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

আমার ফাইল 1। সি

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

এখন আপনি উভয় ফাংশনে একই ডকুমেন্টেশন পাবেন।

এটি আপনাকে কোড ফাইলগুলিতে কম শব্দ দেয় একই সাথে আপনি চূড়ান্ত আউটপুটে বেশ কয়েকটি স্থানে উপস্থাপিত এক জায়গায় ডকুমেন্টেশন পান।

Question 6

সাধারণত আমি .c ফাইলে ইন্টারফেসের (\ প্যারাম, \ রিটার্ন) ডকুমেন্টেশন এবং .c / .cpp / .m ফাইলে প্রয়োগের জন্য ডকুমেন্টেশন (\ বিশদ) রাখি। ডোজিজেন ফাংশন / পদ্ধতির ডকুমেন্টেশনের সমস্ত কিছুকে দলবদ্ধ করে।

Question 7

আমি সমস্ত কিছু হেডার ফাইলে রেখেছি।

আমি সমস্ত কিছু নথিভুক্ত করি তবে কেবলমাত্র সর্বজনীন ইন্টারফেসটি বের করি।

Question 8

আমি প্রোগ্রামিংয়ের জন্য কিউটিক্রিটার ব্যবহার করছি। একটি খুব দরকারী কৌশল কৌশল বা শিরোনাম ফাইলটিতে ঘোষণা পেতে পদ্ধতি বা পদ্ধতিতে Ctrl- ক্লিক ক্লিক করে।

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

Question 9

সি ++ এ কখনও কখনও বাস্তবায়ন শিরোনাম এবং .cpp মডিউলগুলির মধ্যে বিভক্ত হয়। এখানে শিরোনাম ফাইলটিতে এটি ডকুমেন্টেশন রাখা পরিষ্কার বলে মনে হচ্ছে যে সমস্ত পাবলিক ফাংশন এবং পদ্ধতিগুলির গ্যারান্টিযুক্ত এমন একমাত্র জায়গা।