কোড ডকুমেন্টেশন: পাবলিক বনাম অ-পাবলিক?

Question

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

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

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

Answer 1

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

এটি বলে যে, বিমূর্ততা বজায় রাখার জন্য এগুলিকে নন-শিরোনাম উত্স কোডে সীমাবদ্ধ রাখার জন্য (প্রকাশ্যে নথিভুক্ত না করে) একটি বৈধ মামলা হতে পারে।

এই সব বরং বরং বিষয়গত, মনে রাখবেন।

Comments

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

Answer 2

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

ক্লাস শিরোনামে:

• শিরোনাম অন্তর্ভুক্ত (কেন)
• বর্গ সংজ্ঞা সর্বদা (উদ্দেশ্য এবং দায়িত্ব)
• খাঁটি ভার্চুয়াল ফাংশন সর্বদা (সম্পূর্ণ চুক্তি)
• স্ব-ব্যাখ্যামূলক গ্রাহক না হলে ইনলাইন ফাংশন
• স্ব-ব্যাখ্যাযোগ্য না হলে অন্যান্য ঘোষিত প্রকারগুলি
• স্থির তথ্য সদস্য (কেন)
• স্ব-ব্যাখ্যামূলক না হলে অন্য ডেটা সদস্যগণ
• ম্যাক্রো যদি কোনও (চুক্তি এবং কেন)

শ্রেণি প্রয়োগের কোডে:

• স্থানীয় ঘোষণা যেমন শিরোনাম হিসাবে
• ফাংশন সংজ্ঞা সর্বদা (সম্পূর্ণ চুক্তি)
• সদস্য ফাংশন সংজ্ঞা সর্বদা (সম্পূর্ণ চুক্তি বা ভার্চুয়াল ওভাররাইডের মূলের উল্লেখ)
• স্ট্যাটিক ভেরিয়েবল সংজ্ঞায়িত যদি কোন (উদ্দেশ্য কেন)

টেমপ্লেট শিরোনামে:

• উপরের একীভূত এবং
• টেমপ্লেট আর্গুমেন্টের জন্য উপযুক্ত / অনুপযুক্ত প্রকারগুলি এবং
• কতটা উপযুক্ততা স্থিতিশীলভাবে সনাক্ত করা হয়

Answer 3

private:ব্যক্তিগত অধ্যায় শুরুতে সব ডকুমেন্টেশন ব্যবহারকারীদের প্রয়োজন হবে।

Answer 4

ডকুমেন্টেশন যে কোনও দিন মূল্যবান, এটি সংক্ষিপ্তভাবে ব্যবহারের কেস এবং গল্পগুলি ব্যাখ্যা করতে সহায়তা করে। কোডটি কতটা স্বতঃস্ফূর্ত হয় তা ব্যবসায়ের মতো গল্প বলার মতো কয়েক লাইনের মতো ব্যাখ্যা করতে পারে না। কোডটি অবশ্যই ব্যবহারকারীকে যুক্তি দিয়ে মেনে চলার দরকার রয়েছে তা ছাড়াও কী চলছে তা বুঝতে হবে। :-) আমার 2 সেন্ট ...

Comments

ঠিক আছে, তবে আপনি পাবলিক এপিআইয়ের জন্য ডকুমেন্টেশন এবং অভ্যন্তরীণ কাজের জন্য ডকুমেন্টেশনের মধ্যে পার্থক্যটি চিহ্নিত করেন না।

— অরবিটে হালকা ঘোড়দৌড়

Answer 5

স্পষ্টভাবে!

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

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