توصیف یک تابع
توضیح هر تابع در مستندات با همین چند کلمه نوشته میشود: چه میگیرد، چه برمیگرداند، کدام ورودی الزامی است و اگر ندهی چه میشود.
فعل + s
در مستندات مینویسند returns، takes، accepts، throws. فاعل همهی اینها «این تابع» است (یعنی it) و در زمان حال ساده، فعلِ it یک s میگیرد: «The function returns a list». خیلی وقتها فاعل را هم حذف میکنند و جمله با خود فعل شروع میشود: «Returns a list». این جمله دستور نیست؛ اگر دستور بود s نداشت.
هشت کلمهی این درس
returns (ریتِرنز): برمیگرداند؛ پس میدهد
return یعنی برگرداندن. در مستندات تقریباً زیر هر تابع جملهای با returns هست که میگوید جواب تابع چیست. الگوی جمله: «X returns Y» یعنی «X، Y را برمیگرداند». خیلی وقتها فاعل را هم نمینویسند و جمله با خود Returns شروع میشود: «Returns the length of the list». گاهی هم Returns عنوان یک بخش است و زیرش نوع و معنی خروجی میآید.
This method returns the number of items in the list.
این متد تعداد آیتمهای فهرست را برمیگرداند.
takes (تِیکس): میگیرد (به عنوان ورودی)
take یعنی گرفتن. در مستندات «X takes Y» یعنی «X به عنوان ورودی Y را میگیرد». با این فعل میگویند یک تابع چند ورودی دارد و هر کدام چیست: «takes two arguments» یعنی دو آرگومان میگیرد. take یک معنی دیگر هم دارد: «طول کشیدن»، مثل «It takes five seconds».
The function takes two arguments: a name and an age.
این تابع دو آرگومان میگیرد: یک نام و یک سن.
accepts (اَکسِپتس): میپذیرد؛ قبول میکند
accept یعنی پذیرفتن و قبول کردن. «X accepts Y» یعنی «X، Y را به عنوان ورودی قبول میکند». خیلی شبیه takes است، ولی بیشتر وقتی میآید که میخواهند بگویند چه نوع چیزهایی مجاز است: «accepts a string or a list» یعنی هم رشته قبول میکند هم فهرست. اگر چیزی بدهی که accept نمیکند، خطا میگیری.
The color parameter accepts a name or a hex code.
پارامتر color یک نام یا یک کد هگز قبول میکند.
throws (ثرُوز): خطا پرتاب میکند
throw در انگلیسی یعنی پرت کردن، مثل پرت کردن توپ. در برنامهنویسی وقتی تابعی به مشکل میخورد، یک خطا «پرتاب» میکند تا کسی آن را بگیرد (catch). الگوی جمله: «X throws E if…» یعنی «اگر فلان شود، X خطای E میدهد». مستندات JavaScript و Java میگویند throws و مستندات پایتون همین را با raises میگویند.
JSON.parse throws a SyntaxError if the text is not valid JSON.
اگر متن JSON معتبر نباشد، JSON.parse یک SyntaxError پرتاب میکند.
defaults to (دیفالتس تو): اگر ندهی، این مقدار را میگیرد
default یعنی «پیشفرض» و اینجا مثل فعل به کار رفته است. «X defaults to Y» یعنی «اگر برای X چیزی ندهی، Y در نظر گرفته میشود». این الگو را کنار پارامترهای اختیاری میبینی و به تو میگوید اگر آن ورودی را ننویسی چه اتفاقی میافتد. خیلی وقتها کوتاه و بدون فاعل میآید: «Defaults to 10».
The timeout defaults to 30 seconds if you do not set it.
اگر timeout را تنظیم نکنی، ۳۰ ثانیه در نظر گرفته میشود.
optional (آپشِنال): اختیاری؛ میشود ننوشت
option یعنی «گزینه و انتخاب» و optional یعنی چیزی که انتخابش با توست: اگر بخواهی میدهی، اگر نخواهی نمیدهی. در مستندات کنار پارامترهایی نوشته میشود که لازم نیست حتماً مقدار بدهی، چون خودشان یک مقدار پیشفرض دارند. برعکسش required است.
The second argument is optional and defaults to an empty string.
آرگومان دوم اختیاری است و اگر ندهی یک رشتهی خالی در نظر گرفته میشود.
required (ریکوایِرد): الزامی؛ حتماً باید باشد
require یعنی «لازم داشتن». required یعنی «لازمشده»، چیزی که بدون آن کار جلو نمیرود. در مستندات کنار پارامتری میآید که حتماً باید مقدارش را بدهی، وگرنه خطا میگیری. در فرمهای وب هم خانهای که ستاره دارد required است و تا پرش نکنی فرم فرستاده نمیشود.
The name field is required and cannot be empty.
فیلد نام الزامی است و نمیتواند خالی باشد.
default (دیفالت): پیشفرض؛ مقداری که از قبل گذاشتهاند
default مقداری است که وقتی خودت چیزی انتخاب نکردهای به کار میرود. مثل زنگ گوشی نو: تا عوضش نکنی، همان زنگ کارخانه میماند. در مستندات هم اسم است («the default is 10») و هم صفت («the default value»، «the default port»). تنظیمات هر برنامه پر از default است.
The default value of this option is false.
مقدار پیشفرض این گزینه false است.
مستندات یک تابع
find_user(name, limit=10, exact=False)
Takes a name and returns a list of matching users.
Parameters:
name (str): Required. The name to search for.
limit (int): Optional. The maximum number of results. Defaults to 10.
exact (bool): Optional. The default is False.
The name parameter accepts both English and Persian letters.
Throws a ValueError if the name is an empty string.
find_user(name, limit=10, exact=False)
یک نام میگیرد و فهرستی از کاربرهای همخوان برمیگرداند.
پارامترها:
name (رشته): الزامی. نامی که باید جستوجو شود.
limit (عدد صحیح): اختیاری. بیشترین تعداد نتیجهها. اگر ندهی ۱۰ در نظر گرفته میشود.
exact (بولی): اختیاری. پیشفرضش False است.
پارامتر name هم حروف انگلیسی و هم حروف فارسی را میپذیرد.
اگر نام یک رشتهی خالی باشد، یک ValueError پرتاب میکند.