ঠিক আছে, তাই আমি পিইপি 8 এবং পিইপি 257 উভয়ই পড়েছি এবং আমি ফাংশন এবং ক্লাসগুলির জন্য প্রচুর ডক্টাস্ট্রিং লিখেছি, তবে মডিউল ডক্ট্রিংয়ের ক্ষেত্রে কী করা উচিত সে সম্পর্কে আমি কিছুটা অনিশ্চিত। আমি অনুভব করেছি, সর্বনিম্ন, এটি মডিউলটি যে ফাংশন এবং ক্লাসগুলি রফতানি করে তা নথিভুক্ত করা উচিত, তবে আমি এমন কয়েকটি মডিউলও দেখেছি যা লেখকের নাম, কপিরাইট তথ্য ইত্যাদি তালিকাভুক্ত করে anyone কাঠামোগত হতে হবে?
উত্তর:
help(yourmodule)ইন্টারেক্টিভ ইন্টারপ্রেটারের প্রম্পটে কেউ কী করছেন সে সম্পর্কে ভাবুন - তারা কী জানতে চান ? (তথ্য আহরণের এবং প্রদর্শনের অন্যান্য পদ্ধতিগুলি তথ্যের helpপরিমাণের দিক থেকে প্রায় সমান )। সুতরাং আপনি যদি x.py:
"""This module does blah blah."""
class Blah(object):
"""This class does blah blah."""তারপর:
>>> import x; help(x)শো:
Help on module x:
NAME
x - This module does blah blah.
FILE
/tmp/x.py
CLASSES
__builtin__.object
Blah
class Blah(__builtin__.object)
| This class does blah blah.
|
| Data and other attributes defined here:
|
| __dict__ = <dictproxy object>
| dictionary for instance variables (if defined)
|
| __weakref__ = <attribute '__weakref__' of 'Blah' objects>
| list of weak references to the object (if defined)আপনি দেখতে পাচ্ছেন, ক্লাসগুলির বিস্তারিত তথ্য (এবং এখানেও আমি প্রদর্শন করছি না এমনকী ফাংশনগুলি) ইতিমধ্যে সেই উপাদানগুলির ডকাস্ট্রিংগুলি অন্তর্ভুক্ত করা হয়েছে; মডিউলের নিজস্ব ডক্ট্রিংগুলিতে এগুলি খুব সংক্ষিপ্তভাবে বর্ণনা করা উচিত (যদি আদৌ হয়) এবং পরিবর্তে সামগ্রিকভাবে মডিউল আপনার জন্য কী করতে পারে তার একটি সংক্ষিপ্তসারকে মনোনিবেশ করা উচিত, আদর্শভাবে কিছু দলিলযুক্ত উদাহরণ (যেমন ফাংশন এবং শ্রেণীর মতো আদর্শে ডক্টেস্টেড উদাহরণ থাকা উচিত) তাদের ডক্টরিস্টিং)।
লেখকের নাম এবং কপিরাইট / লাইসেন্সের মতো মেটাডাটা মডিউলটির ব্যবহারকারীকে কীভাবে সহায়তা করে তা আমি দেখতে পাই না - এটি বরং মন্তব্যগুলিতে যেতে পারে, কারণ এটি মডিউলটিকে পুনরায় ব্যবহার বা সংশোধন করতে হবে কিনা তা বিবেচনা করে কাউকে সহায়তা করতে পারে।
help()কেবল কোডটি পড়েন তাদের চেয়ে দোভাষীটিতে এই পদ্ধতিটি বেশি ব্যবহার করেন ।
বিশেষ উল্লেখ উদ্ধৃতি :
একটি স্ক্রিপ্টের ডক্ট্রিং (একটি একা একা থাকা প্রোগ্রামের) তার "ব্যবহার" বার্তা হিসাবে ব্যবহারযোগ্য হওয়া উচিত, যখন স্ক্রিপ্টটি ভুল বা অনুপস্থিত যুক্তি (বা সম্ভবত "-h" বিকল্পের সাহায্যে, "সহায়তা") সহ প্রেরণ করা হয় printed এই জাতীয় কোনও ডকস্ট্রিংয়ের স্ক্রিপ্টের ফাংশন এবং কমান্ড লাইন সিনট্যাক্স, এনভায়রনমেন্ট ভেরিয়েবল এবং ফাইলগুলি ডকুমেন্ট করা উচিত। ব্যবহারের বার্তাগুলি মোটামুটি বিস্তৃত হতে পারে (বেশ কয়েকটি পর্দা পূর্ণ) এবং একটি নতুন ব্যবহারকারীর পক্ষে কমান্ডটি সঠিকভাবে ব্যবহার করার জন্য পর্যাপ্ত হওয়া উচিত, পাশাপাশি পরিশীলিত ব্যবহারকারীর জন্য সমস্ত বিকল্প এবং যুক্তির একটি সম্পূর্ণ দ্রুত রেফারেন্স থাকতে হবে।
একটি জন্য docstring মডিউল সাধারণত ক্লাস, ব্যতিক্রম এবং ফাংশন (এবং অন্য কোন বস্তু) যে প্রতিটি এক লাইন সারসংক্ষেপ সঙ্গে, মডিউল দ্বারা রপ্তানি করা হয় তালিকা প্রস্তুত করা উচিত নয়। (এই সংক্ষিপ্তসারগুলি সাধারণত অবজেক্টের ডকাস্ট্রিংয়ের সারসংক্ষেপ রেখার চেয়ে কম বিশদ দেয়)) প্যাকেজের জন্য ডকাস্ট্রিং (অর্থাত্ প্যাকেজের
__init__.pyমডিউলটির ডকস্ট্রিং ) এছাড়াও প্যাকেজের দ্বারা রফতানি করা মডিউল এবং সাব- প্যাকেজগুলির তালিকাবদ্ধ হওয়া উচিত।কোনও শ্রেণীর জন্য ডক্ট্রিং এর আচরণের সংক্ষিপ্তসার এবং সর্বজনীন পদ্ধতি এবং উদাহরণ ভেরিয়েবলগুলি তালিকাভুক্ত করা উচিত। যদি ক্লাসটি সাবক্লাস করার উদ্দেশ্যে করা হয়, এবং সাবক্লাসগুলির জন্য একটি অতিরিক্ত ইন্টারফেস রয়েছে, এই ইন্টারফেসটি আলাদাভাবে তালিকাভুক্ত করা উচিত (ডক্ট্রিংয়ে)। শ্রেণি নির্মাতা তার
__init__পদ্ধতির জন্য ডক্ট্রিংয়ে নথিভুক্ত করা উচিত । স্বতন্ত্র পদ্ধতিগুলি তাদের নিজস্ব ডকাস্ট্রিং দ্বারা নথিভুক্ত করা উচিত।
কোনও ফাংশন বা পদ্ধতির ডক্ট্রিং একটি শব্দসমষ্টি যা একটি পিরিয়ডে শেষ হয়। এটি কোনও কমান্ড হিসাবে ফাংশন বা পদ্ধতির প্রভাব নির্ধারণ করে ("এটি করুন", "এটি ফিরিয়ে দিন"), বিবরণ হিসাবে নয়; যেমন "পথের নামটি ফেরায় ..." লিখবেন না। কোনও ক্রিয়াকলাপ বা পদ্ধতির জন্য একটি মাল্টলাইন-ডাস্ট্রিংয়ের তার আচরণটি সংক্ষিপ্ত করে এবং তার যুক্তিগুলি, রিটার্নের মান (গুলি), পার্শ্ব প্রতিক্রিয়াগুলি, উত্থাপিত ব্যতিক্রমগুলি, এবং কখন ডাকা যাবে (যখন প্রযোজ্য) সমস্তই প্রযোজ্য) এগুলি নথিভুক্ত করা উচিত। .চ্ছিক যুক্তি নির্দেশ করা উচিত। কীওয়ার্ড আর্গুমেন্টগুলি ইন্টারফেসের অংশ কিনা তা নথিভুক্ত করা উচিত।