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

Question

আমি আমার সত্তা, বিজনেস লজিক এবং ডেটা অ্যাক্সেস ক্লাসগুলির জন্য তথ্যমূলক শ্রেণির ডকুমেন্টেশন ফর্ম্যাট খুঁজছি।

আমি এখান থেকে নিম্নলিখিত দুটি ফর্ম্যাট খুঁজে পেয়েছি

ফরম্যাট ঘ

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

ফর্ম্যাট 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

আমি বোধ করি নীচের মূল উপাদানগুলি

• লেখক
• তৈরীর তারিখ
• বিবরণ
• পরিবর্ধন ও পরিবর্তন তালিকা

যেমন নেমস্পেস এবং ক্লাসের নাম যাইহোক সেখানে থাকবে।

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

Comments

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

— ক্রিস

লেখক এবং তৈরি তারিখটি উত্স নিয়ন্ত্রণ দ্বারা পরিচালিত হয়। আপনার যা দরকার তা হ'ল একটি বিবরণ।

— মাইক সিমুর

Answer 1

আপনি প্রস্তাবিত বেশিরভাগ তথ্য উত্স ভান্ডারে পাওয়া যাবে।

আপনার কেবলমাত্র প্রয়োজনীয় জিনিসটি হ'ল উদ্দেশ্য বিভাগ, যা ক্লাসের জন্য কী আছে তা বলে।

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

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

Answer 2

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

জেফ আতউডের এই নিবন্ধটি পড়ুন - কোনও মন্তব্য ছাড়াই কোডিং ।

Comments

পারলে আমি এই উত্তরটি +100-এ ভোট দেব।

— ক্রিস হোমস

Answer 3

ডকুমেন্টেশন উত্পন্ন করতে আমি স্ট্যান্ডার্ড ট্যাগ ব্যবহার করি। বেশিও না কমও না. এখানে দেখো

আমি ক্লাসের অন্তর্গত নয় এমন তথ্য কখনও রাখি না। লেখক, ডেটা এবং রিভিশনগুলি কোনও সংস্করণ নিয়ন্ত্রণ সিস্টেমে সংরক্ষণ করার ডেটা।

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

Answer 4

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

Comments

@ কারিয়ান্না - সুতরাং আপনি শ্রেণীর বিবরণ ব্যতীত সমস্ত কিছু সোর্স কন্ট্রোল রিপোজিটরিতে ছেড়ে দেওয়ার পরামর্শ দিচ্ছেন; তবে, প্রতিবার এটি সংগ্রহস্থল লগ থেকে দেখার জন্য কি ক্লান্তিকর হবে? এবং আমি যদি ডকুমেন্টেশন ফাইল (.chm বা স্যান্ডক্যাসলের মতো) তৈরি করতে চাই তবে কী হবে?

— কোডারহক

@ স্যান্ডি আপনার কোড মন্তব্য শিরোনামে আপনার নির্দিষ্ট কীওয়ার্ডগুলি রাখতে সক্ষম হবেন যে প্রতিবার আপনি যাচাই করে নেবেন আপনার উত্স নিয়ন্ত্রণের সংগ্রহস্থলটি আপডেট হবে It আপনি কোন ভাষায় কোডিং করছেন এবং কোন উত্স নিয়ন্ত্রণ রেপো আপনি ব্যবহার করছেন তার উপর নির্ভর করে। আপনি কি ব্যবহার করছেন? :)

— মার্টিজন ভার্বার্গ

@ করিয়ানা - আমি সাবভারশন ব্যবহার করছি; আশা করি লিটল টেক / প্রোগ্রামিং নিয়ে আলোচনা এটিকে বন্ধ করে দিবে না! :-) দয়া করে আমাকে জানিয়ে দিন যে আমাকে কীভাবে নির্দিষ্ট শ্রেণিতে লগ মন্তব্যটি মার্জ করতে হবে তা জিজ্ঞাসা করে একটি প্রশ্ন পোস্ট করতে হবে? :-)

— কোডারহক

আপনি $ আইডি: $ এবং $ ইউআরএল: use ব্যবহার করতে পারেন, এটি: alচ্ছিক হতে পারে, আমি ভুলে গেছি। আশা করি এসও ওভারলর্ডরা আমাদের নিন্দার জন্য আমাদের হত্যা করবে না

— মার্টিজান ভারবার্গ

Answer 5

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

আপনার ক্লাসটি কী করছে তা নির্ধারণ করতে যদি আমাকে আপনার "বিবরণ" পড়তে হয় তবে (ক) আপনার নামটি খারাপভাবে লেখা হয়েছে বা (খ) আপনি একটি খারাপ ক্লাস লিখেছেন যা খুব বেশি করছে (এসআরপি)।

Answer 6

আমি আমার শিরোনামের টেম্পলেটগুলি পরিবর্তন করার সাথে সাথে খেলছিলাম, অন্যরা যেমন বলেছে যে এই তথ্যগুলির অনেকগুলি সংগ্রহস্থলটিতে পাওয়া যায় এবং এখন পর্যন্ত যে বড় বড় ক্ষেত্রগুলি আমি রাখার সন্ধান করছিলাম সেগুলি হ'ল নিম্নলিখিতটি:

• বিবরণ - কোড দ্বারা কী করা হচ্ছে।
• নোটস - কোড সম্পর্কে যে কোনও কিছু যা জানা দরকার যা কোডটিতে থাকা মন্তব্য থেকে সহজেই পাওয়া যায় না।
• তথ্যসূত্র - কোডের উপর নির্ভর করে এমন কোনও রেফারেন্স ব্যবহার includeবা অনুরূপ বিবৃতিগুলি পরিষ্কার করা হয় না ।

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

Answer 7

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

সোর্সকোড যেহেতু সংগ্রহশালার সাথে সংযোগটি আলগা করতে পারে (যেমন অনুলিপি করা হয়) আমার ক্লাস ডকুমেন্টেশনটি এরকম হয়:

• class documentation header (= ফাইলের শুরুতে মন্তব্য ব্লক) কেবলমাত্র প্রয়োজনীয় আইনী ইনফোস (অর্থাত্ জিপিএল-লাইসেন্সের অধীনে xyz দ্বারা কপিরাইট) রয়েছে
• কোনও বিকাশকারী যা ক্লাস ব্যবহার করে তা অবশ্যই ক্লাস-জাভা-ডক-মন্তব্যে (বা এর নেট নেট সমতুল্য) intoুকে যেতে হবে যাতে আধুনিক আদর্শ-বর্গ ক্লাসটি ব্যবহার করে এমন সরঞ্জামদণ্ড তথ্য ইনকোর্সকোড হিসাবে এই তথ্যটি প্রদর্শন করতে পারে।

---

আপনি বাগফিক্স বা বৈশিষ্ট্য-অনুরোধের জন্য টিকিট সংখ্যাটিও যুক্ত করতে পারেন যাতে ক্লাসটি কখন / কখন / কেন তৈরি হয়েছিল (আপনার ভাগ্যবান যদি ভাবা হয় যে আপনি কয়েক বছর পরেও টিকিট অ্যাক্সেস করতে পারেন) some

যখন মৌমাছিটি পুরানো ক্লোজড-সোর্স লিগ্যাসি প্রোগ্রামগুলিতে সমস্যাগুলি ঠিক করতে বলেছিল তখন কোডটির মূল প্রয়োজনীয়তা বুঝতে আমার পক্ষে মূল্যবান valuable