نظر دادن کد پایتون

برنامه نویسی منعکس کننده طرز تفکر شما است تا تنها مراحلی را که برای حل یک مشکل با استفاده از رایانه برداشته اید، توصیف کند. کامنت گذاشتن کد به توضیح افکار شما کمک می کند process، و به شما و دیگران کمک می کند تا بعدا متوجه شوید روی قصد کد شما این به شما امکان می دهد خطاها را راحت تر پیدا کنید، آنها را برطرف کنید و بعداً کد را بهبود بخشید onو برای استفاده مجدد از آن در سایر برنامه ها نیز.

نظر دادن برای همه انواع پروژه ها مهم است، مهم نیست که کوچک، متوسط ​​یا بزرگ باشند. این بخش ضروری از گردش کار شما است و به عنوان تمرین خوبی برای توسعه دهندگان تلقی می شود. بدون نظر، همه چیز می تواند گیج کننده باشد، به سرعت. در این مقاله روش‌های مختلف اظهار نظر پشتیبانی‌های پایتون و روش استفاده از آن برای ایجاد خودکار اسناد برای کد شما با استفاده از به اصطلاح رشته‌های مستند سطح ماژول را توضیح خواهیم داد.

به همان اندازه که نظرات مهم هستند، هنوز هم امکان نوشتن نظرات بد وجود دارد. آنها باید همیشه کوتاه، مستقیم به اصل مطلب باشند و ارزش آموزنده ای به آن اضافه کنند.

به عنوان مثال، این یک نظر نسبتاً بی فایده است:

b = 56                       

مثال بعدی در عوض یک نظر مفیدتر را نشان می‌دهد و با نام‌گذاری واضح متغیرها همراه است:

salestax10 = 1.10            
salestax20 = 1.20            

تعداد بی نهایت سناریو دیگری وجود دارد که نظرات را تضمین می کند. این فقط یک نمونه است. یک قانون سرانگشتی خوب این است که برای هر خط کد (مانند درک لیست) یا بخشی از کد که هدف آن مشخص نیست، نظر اضافه کنید. این بسیار ذهنی است و در واقع مهارتی است که باید آموخته شود.

یک نظر در پایتون با کاراکتر هش شروع می شود، #، و تا انتهای خط فیزیکی گسترش می یابد. هر چند یک کاراکتر هش در یک مقدار رشته به عنوان نظر دیده نمی شود. به طور دقیق، یک نظر را می توان به سه روش نوشت – به طور کامل روی خط خودش، در کنار یک بیانیه کد، و به عنوان یک بلوک نظرات چند خطی.

در بخش های بعدی هر نوع نظر را توضیح خواهم داد.

چنین نظری با یک کاراکتر هش شروع می شود (#) و بعد از آن متنی حاوی توضیحات بیشتر است.

postCode = 75000

همچنین می توانید در کنار عبارت کد یک نظر بنویسید. مثال بعدی نشان می دهد که:

product = {
    "productId": 0,          
    "description": "",       
    "categoryId": 0,         
    "price": 0.00            
}

راهنمای سبک برای کد پایتون (PEP8) کمتر از 79 کاراکتر در هر خط را توصیه می کند. در عمل، خواندن 70 یا 72 کاراکتر در هر خط آسان تر است، و بنابراین توصیه می شود. اگر نظر شما به این طول نزدیک می شود یا بیشتر از آن است، می خواهید آن را در چندین خط پخش کنید.

همانطور که در بالا ذکر شد، کل بلوک نظرات توسط پایتون نیز قابل درک است. این نظرات به عنوان اسناد درون خطی برای دیگرانی که کد شما را می خوانند، عمل می کنند و معمولاً چیزها را با جزئیات بیشتری توضیح می دهند.

از نظر فنی پایتون از نظرات چند خطی پشتیبانی نمی‌کند، بنابراین گزینه‌های زیر توسط برخی به عنوان راه‌حل در نظر گرفته می‌شوند، اما همچنان برای نظرات چند خطی کار می‌کنند.

نسخه 1 نظرات تک خطی را به صورت زیر ترکیب می کند:

نسخه 2 ساده تر از نسخه 1 است. در ابتدا برای ایجاد مستندات در نظر گرفته شده است (در این مورد بیشتر را در زیر ببینید)، اما همچنین می تواند برای نظرات چند خطی استفاده شود.

"""
LinuxThingy version 1.6.5

Parameters:

-t (--text): show the text interface
-h (--help): display this help
"""

توجه داشته باشید که نسخه اخیر باید در گیومه های خاص قرار گیرد (""") برای کار کردن، و نه هش کاراکترها.

تمرین رایج

شروع یک فایل پایتون با چند خط کامنت بسیار معمول است. این خطوط اطلاعاتی در مورد پروژه، هدف فایل، برنامه نویسی که آن را توسعه داده یا کار کرده است را بیان می کند روی آن و مجوز نرم افزاری که برای کد استفاده می شود.

این قطعه از یکی از نمونه هایی که برای اهداف آموزشی استفاده می کنم، گرفته شده است. نظر با توضیحات شروع می شود و پس از آن اعلامیه حق چاپ با نام من و سال انتشار کد ارسال می شود. در زیر خواهید دید که کد تحت مجوز است GNU مجوز عمومی (GPL). برای تماس با من آدرس ایمیل من نیز در آنجا اضافه شده است.

پایتون یک مفهوم داخلی به نام docstrings دارد که راهی عالی برای مرتبط کردن اسنادی که نوشته‌اید با ماژول‌ها، توابع، کلاس‌ها و متدهای پایتون است. یک Docstring به عنوان یک نظر درست در زیر تابع، ماژول یا سر شیء اضافه می شود و توصیف می کند که تابع، ماژول یا شی چه کاری انجام می دهد. انتظار می رود از این قوانین پیروی کند:

• رشته مستند یا یک خطی است یا یک نظر چند خطی. در مورد دوم، خط اول یک توضیح کوتاه است و بعد از خط اول یک خط خالی دنبال می شود.

• رشته را با حرف بزرگ شروع کنید و با نقطه پایان دهید.

این یک مثال اساسی از آنچه به نظر می رسد است:

def add(value1, value2):
    """Calculate the sum of value1 and value2."""
    return value1 + value2

در سیستم کمک تعاملی پایتون، رشته مستند از طریق در دسترس قرار می گیرد __doc__ صفت.

>>> print add.__doc__
Calculate the sum of value1 and value2.

تعدادی ابزار وجود دارد که به طور خودکار اسناد را از رشته‌های اسنادی تولید می‌کنند، مانند داکسیژن، PyDoc، pdoc، و autodoc پسوند برای Sphinx. در ادامه مقاله روش کار با آنها را به شما توضیح خواهیم داد.

نتیجه

نوشتن نظرات مناسب در کد پایتون آنقدرها هم پیچیده نیست و فقط به قدرت استقامت نیاز دارید. این به همه ما کمک می کند که سعی می کنیم کد شما را بفهمیم، از جمله خودتان برای زمانی که در تاریخ بعدی دوباره کد خود را مشاهده می کنید. امیدواریم توصیه‌هایی که در اینجا به شما داده‌ایم، ایجاد نظرات و مستندات بهتر در کدتان را برای شما آسان‌تر کند.

سپاسگزاریها

نویسنده مایل است از نظرات انتقادی زولکا هافمن هنگام تهیه این مقاله تشکر کند.