ডকস্ট্রিং কি?
ডকস্ট্রিং (Documentation String) হলো ফাংশন, ক্লাস, মডিউল বা মেথডের সংজ্ঞার ঠিক পরে লেখা একটি স্ট্রিং লিটারেল যা __doc__ অ্যাট্রিবিউটে স্টোর হয় এবং help() ফাংশন দিয়ে অ্যাক্সেস করা যায়। এটি কমেন্ট নয়, এক্সিকিউটেবল কোডের অংশ।
সিঙ্গেল-লাইন ডকস্ট্রিং
def add_nums(x):
'''একটি সংখ্যাকে নিজের সাথে যোগ করে ফেরত দেয়।'''
return x + x
print(add_nums.__doc__)
# আউটপুট: একটি সংখ্যাকে নিজের সাথে যোগ করে ফেরত দেয়।মাল্টি-লাইন ডকস্ট্রিং (PEP 257 סט্যান্ডার্ড)
- প্রথম লাইনে সংক্ষিপ্ত সারাংশ (১ লাইন)।
- খালি একটি লাইন।
- বিস্তারিত বিবরণ, আর্গুমেন্ট, রিটার্ন ভ্যালু, এক্সেপশন ইত্যাদি।
def fibonacci(n):
'''ফিবোনাচি সিকোয়েন্সের n-তম সংখ্যা রিটার্ন করে।
Args:
n (int): সিকোয়েন্সের পজিশন (0-ইনডেক্সড)।
Returns:
int: n-তম ফিবোনাচি সংখ্যা।
Raises:
ValueError: যদি n নেতিবাচক হয়।
'''
if n < 0:
raise ValueError("n must be non-negative")
a, b = 0, 1
for _ in range(n):
a, b = b, a + b
return a
print(fibonacci.__doc__)বিল্ট-ইন অবজেক্টের ডকস্ট্রিং অ্যাক্সেস
print(list.__doc__)
# আউটপুট: Built-in mutable sequence. If no argument is given, the constructor creates a new empty list...
print(print.__doc__)
# আউটপুট: print(value, ..., sep=' ', end='\\n', file=sys.stdout, flush=False)ইন্ডেন্টেশন নিয়ম
- প্রথম লাইনের ইন্ডেন্টেশন নগণ্য (অপ্রাসঙ্গিক)।
- বাকি লাইনগুলোর রিলেটিভ ইন্ডেন্টেশন সংরক্ষিত থাকে।
- ত্রি-উদ্ধৃতি (triple quotes) এর সাথে সেলাইনমেন্ট মেইন্টেইন করুন।
ডকস্ট্রিং ভালো লিখার টিপস
- Imperative Mood: "Return the sum" (নয় "Returns the sum")।
- Args/Returns/Raises সেকশন স্পষ্ট রাখুন।
- Type Hints ফাংশন সিগ্নেচারেই দিন, ডকস্ট্রিং-এ ডুপ্লিকেট না করুন।
- Tools: Sphinx, pdoc, MkDocs দিয়ে HTML ডকুমেন্টেশন জেনারেট করুন।
