docstring یعنی چه؟
تلفظ: داکاِسترینگ · نوع: اسم
معنی docstring: متن راهنمای یک تابع، درون خود کد
docstring از دو تکه ساخته شده: doc (کوتاهشدهی documentation، یعنی مستندات) و string (رشته). در پایتون، رشتهای است که درست زیر خط def مینویسی و میگوید این تابع چه میگیرد و چه برمیگرداند. فرقش با کامنت این است که پایتون آن را نگه میدارد و با help() نشانش میدهد. جملهی اولش کوتاه است و با فعل شروع میشود: Return…، Calculate…
docstring در جمله
Every public function should have a docstring with a short example.
هر تابع عمومی باید یک داکاسترینگ با یک مثال کوتاه داشته باشد.
docstring در کد
def area(width, height):
"""Return the area of a rectangle."""
return width * heightسه گیومهی دوتایی، یک جملهی کوتاه، و نقطه در آخر.
نکته
در جاوااسکریپت همین کار را با کامنتهای /** … */ میکنند که اسمش JSDoc است.
کلمههای مرتبط
- documentation: مستندات؛ نوشتههای راهنمای یک ابزار
- code comment: توضیحی که برای آدمها کنار کد مینویسی
- returns: برمیگرداند؛ پس میدهد
درس این کلمه
docstring یکی از هشت کلمهی درس «کامنت» در فاز 9: نوشتن از دورهی انگلیسی برای برنامهنویسها است. بقیهی کلمههای این درس:
- code comment: توضیحی که برای آدمها کنار کد مینویسی
- TODO: کاری که هنوز باید انجام شود
- FIXME: نشانهی کدی که خراب است و باید درست شود
- description: توضیح، شرح
- summary: خلاصه
- explanation: توضیحِ دلیل یا روش کار
- readable: خوانا، راحت برای خواندن