Tác giả. Sahil [Bạn cũng có thể viết bài trên thatascience. Liên hệ chúng tôi]
Sửa đổi lần cuối. 2 Tháng một, 2022
Bình luận trong Python là gì?
Đầu tiên trong Hướng dẫn về Nhận xét và Tài liệu, chúng ta sẽ nói về Nhận xét vì chúng phổ biến hơn và dễ hiểu hơn
- Nhận xét là các câu lệnh không thể thực thi được trong Python. Điều đó có nghĩa là cả trình biên dịch python và PVM sẽ không thực thi chúng. Nhận xét dành cho sự hiểu biết của con người, không dành cho trình biên dịch hoặc PVM
- Nhận xét mã của bạn giúp giải thích quá trình suy nghĩ của bạn và giúp bạn và những người khác hiểu ý định mã của bạn
- Nhận xét là quan trọng đối với tất cả các loại dự án, bất kể chúng là gì – nhỏ, trung bình hay khá lớn. Đây là một phần thiết yếu trong quy trình làm việc của bạn và là một phương pháp hay dành cho nhà phát triển
- Trong hướng dẫn này, chúng tôi sẽ đề cập đến một số khái niệm cơ bản về viết nhận xét bằng Python
Tại sao chúng ta sử dụng Bình luận?
- Công dụng chính của nhận xét như đã đề cập trước đó là giải thích mã cho người dùng theo cách có ý nghĩa và hữu ích mà không có bất kỳ sự phức tạp nào
- Mục tiêu của chúng tôi với một nhận xét nhất định phải luôn đơn giản hóa mã để người dùng dễ hiểu hơn
[Bán tại. [X=10 #Điều này gán giá trị 10 cho biến X chỉ tỷ lệ phần trăm lỗi. ] Nhận xét cung cấp ngữ cảnh và tránh nhầm lẫn. ]
- Nhận xét cũng có thể được sử dụng để làm cho mã dễ đọc hơn
- Một cách sử dụng bình luận độc đáo đến từ việc sử dụng bình luận để ngăn một số phần nhất định của mã thực thi
[Bán tại. [A=20
B=30
#C=40],
Giả sử vì lý do nào đó chúng ta muốn gán một giá trị cho C ngay bây giờ,
Sau đó, bằng cách sử dụng nhận xét, chúng tôi có thể tắt dòng cụ thể đó
Làm cách nào để tạo nhận xét trong Python?
- Một nhận xét trong Python bắt đầu bằng ký tự băm, # và kéo dài đến cuối dòng vật lý
- Việc sử dụng các chú thích trong python rất dễ dàng, bạn có thể đưa một dòng chú thích vào mã của mình khá dễ dàng
- Cũng có thể sử dụng Ba trích dẫn [‘’’] cho nhận xét nhiều dòng
[Bán tại. [Print[“hello world”] #đây là mã để in hello world]]
Tài liệu trong Python là gì?
Các tài liệu Python là các chuỗi ký tự xuất hiện ngay sau định nghĩa của hàm, phương thức, lớp hoặc mô-đun
- Nó là một tài liệu được chỉ định cho mã viết. Không giống như các chú thích mã thông thường, tiến sĩ nên mô tả chức năng của một chức năng chứ không phải cách thức hoạt động của nó
- Một số loại Tài liệu khác nhau là
Tại sao chúng ta sử dụng Docstrings?
Tài liệu giúp bạn hiểu khả năng của một mô-đun hoặc chức năng
Ví dụ: giả sử bạn đã cài đặt thư viện gấu trúc và bạn muốn biết tất cả về pandas packages.
Bạn chỉ cần sử dụng chức năng trợ giúp để lấy tất cả thông tin.
[Bán tại. [trợ giúp[gấu trúc]]]
- Các tài liệu cho phép chúng tôi mô tả công việc thực tế của một chức năng sẽ được thực hiện bởi nó
[Bán tại. [def vuông [a]
‘’’Biến đầu vào a là bình phương’’’
trả lại một**a]]
Chúng tôi sử dụng Docstrings như thế nào?
- Python Docstrings có cú pháp tương tự như cú pháp bình luận. Chuỗi tài liệu phải được chứa bên trong ba dấu ngoặc kép [‘’’]
- I. e. , mọi thứ bên trong dấu ngoặc kép được coi là một chuỗi tài liệu cho hàm cụ thể đó, tương tự như cách thức hoạt động của nhận xét nhiều dòng
- Không giống như Nhận xét, Tài liệu không thể bắt đầu từ bất kỳ đâu bên trong mã. Một Docstring chỉ có thể được tạo bên trong một hàm, lớp hoặc mô-đun
[Bán tại. [thêm chắc chắn [a, b]
‘’’Thực hiện cộng các biến đầu vào đã cho
Thông số. int, int [hai số lấy từ người dùng để cộng]
trả lại. int [kết quả là phép cộng của hai số]‘’’
c = a + b
trở lại c]]
- Chuỗi tài liệu của hàm do người dùng xác định có thể được hiển thị bằng thuộc tính __doc__. Xem xét ví dụ trên, chúng ta có thể sử dụng print[add. __doc__] để hiển thị chuỗi tài liệu cho hàm cụ thể đó.
- Có thể dễ dàng truy cập Chuỗi tài liệu cho hàm tích hợp bằng cách sử dụng phương pháp tương tự i. e. , in[in. __doc__] sẽ cung cấp cho chúng tôi Chuỗi tài liệu cho hàm print[] tích hợp và cung cấp cho chúng tôi kết quả đầu ra như.
print[value, …, sep=’ ‘, end=’\n’, file=sys. thiết bị xuất chuẩn, flush=False]In giá trị vào luồng hoặc tới hệ thống. thiết bị xuất chuẩn theo mặc định
Đối số từ khóa tùy chọn. tập tin. một đối tượng giống như tệp [luồng]; . tiêu chuẩn. tháng chín. chuỗi được chèn giữa các giá trị, mặc định là khoảng trắng
kết thúc. chuỗi được nối sau giá trị cuối cùng, mặc định một dòng mới
tuôn ra. có nên buộc xả luồng không
Sự khác biệt giữa Comments và Docstrings trong Python
Đây là một chủ đề mà hầu hết mọi người dường như gặp rắc rối với,
Và nên được coi là cực kỳ quan trọng để hiểu trong Nhận xét và Tài liệu trong Python
Khi nào tôi sử dụng nhận xét?
Vì vậy, để làm cho chủ đề này dễ hiểu hơn nhiều, chúng tôi đã tạo một bảng đơn giản giúp chúng tôi lựa chọn giữa các chuỗi tài liệu/nhận xét
Nhận xét đơn và nhiều dòng
Về cơ bản, có hai cách để chúng ta có thể sử dụng nhận xét trong mã của mình. e. , chú thích một dòng hoặc chú thích nhiều dòng
- Nhận xét một dòng
- Nhận xét một dòng được tạo đơn giản bằng cách bắt đầu một dòng bằng ký tự băm [#]
- Chúng được tự động kết thúc ở cuối dòng
- [Bán tại. [#Đây là nhận xét một dòng]]
2. Nhận xét nhiều dòng
- Nhận xét nhiều dòng trong Python là một đoạn văn bản được đặt trong dấu phân cách [“””] ở mỗi đầu của nhận xét
- Chúng cần được chấm dứt bằng cách sử dụng dấu phân cách [“””] ở cuối nhận xét
- [Bán tại. [in[“xin chào thế giới”]
- “”” Đây là một nhận xét nhiều dòng và chúng tôi có thể sử dụng nó để giải thích hoạt động của mã”””]]
Làm thế nào để viết bình luận tốt bằng Python?
- Khi người khác đọc mã của bạn, rất có khả năng họ sẽ không xem qua từng dòng mã của bạn và đây là lúc các nhận xét xuất hiện để giúp tiết kiệm thời gian của họ.
- Mục tiêu của một bình luận phải luôn là cung cấp thông tin chính xác cho người đọc một cách đơn giản và nhanh chóng
- Trong phần này, chúng tôi sẽ cung cấp cho bạn một số mẹo có thể giúp bạn viết bình luận hay trong python
- Luôn cố gắng thêm nhận xét nội tuyến cho một chức năng phức tạp
Các chức năng phức tạp không dễ hiểu đối với người đọc có thể được hiểu đơn giản hơn nhiều với sự trợ giúp của nhận xét nội tuyến đưa ra mô tả ngắn về chức năng
2. Luôn cố gắng tỏ ra chuyên nghiệp khi viết bình luận. Đừng bao giờ tỏ ra thân thiện hay đùa giỡn khi viết bình luận, hãy luôn tiếp cận người đọc một cách chuyên nghiệp. Nếu các bình luận không được chỉnh sửa, chúng thậm chí có thể đến tay khách hàng
3. Cố gắng tránh lặp lại chính mình trong một bình luận
- Mục tiêu chính của bạn khi viết bình luận phải luôn là tránh nhầm lẫn và tiết kiệm thời gian của người đọc. Bằng cách lặp lại chính mình trong một bình luận, bạn sẽ lãng phí thời gian quý báu của khách hàng
Ví dụ. x = a*a #x lưu trữ giá trị của a*a [Nhận xét này hoàn toàn không cung cấp nội dung mới cho khách hàng và chỉ lãng phí thời gian của họ] Vì vậy, chúng ta nên tránh viết những nhận xét như vậy
4. Tránh viết mã có mùi
- Nếu có bất kỳ loại lỗi nào trong mã của bạn, đừng bao giờ cố gắng biện minh cho lỗi đó bằng cách sử dụng nhận xét, đó được coi là một cách làm không tốt và có thể khiến bạn gặp rắc rối trong sự nghiệp của mình
- Nếu mã của bạn gặp sự cố, hãy cố gắng sửa mã theo cách thủ công vì sẽ không có nhiều bình luận để sửa mã cho khách hàng
Tài liệu đơn và nhiều dòng
- Docstrings dòng đơn
- Rõ ràng từ cái tên, các loại Tài liệu này bắt đầu và kết thúc trên cùng một dòng
- Chúng bắt đầu và kết thúc bằng việc sử dụng dấu phân cách [“””] và chỉ được sử dụng để cung cấp các chi tiết nhỏ về chức năng hoặc lớp cụ thể
- [Bán tại. [def script_run[bản thân, tập lệnh]. “””Kiểm tra xem tập lệnh có chạy đúng không”””]]
2. Tài liệu nhiều dòng
- Chuỗi tài liệu nhiều dòng bao gồm một dòng tóm tắt giống như chuỗi tài liệu một dòng, theo sau là một dòng trống, tiếp theo là mô tả phức tạp hơn
- Chuỗi tài liệu cho một mô-đun thường liệt kê các lớp, ngoại lệ và chức năng [và bất kỳ đối tượng nào khác]
- Được xuất bởi mô-đun, với một bản tóm tắt một dòng của mỗi
- [Bán tại. [def set_error[self, err]
“””Đặt giá trị lỗi
Giá trị của tham số err được lưu dưới dạng giá trị trong biến lớp error. Giá trị đã cho được chuyển đổi thành giá trị float nếu chưa được thực hiện
lỗi tham số. giá trị lỗi
loại lỗi. trôi nổi
Trở lại. Không có gì"""
bản thân. err = float[err]
Trở lại]]
Các loại Docstring khác nhau
Bây giờ, chúng ta hãy xem các loại Tài liệu khác nhau mà chúng ta có thể sử dụng trong Python. Chúng được liệt kê và giải thích như sau
- Tài liệu lớp học
- Tài liệu lớp được tạo cho chính lớp đó, cũng như bất kỳ phương thức lớp nào
- Class Docstrings cần được đặt ngay sau phần khai báo lớp
- Một Class Docstring phù hợp phải chứa một bản tóm tắt ngắn gọn về mục đích và hành vi của nó và Bất kỳ thuộc tính nào của lớp
[Bán tại. [lớp SimpClass
“””Chuỗi tài liệu lớp học ở đây. ”””
chắc chắn xin chào[]
“””Chuỗi tài liệu về phương thức lớp ở đây. ”””
in ["xin chào thế giới"]
2. Chuỗi tài liệu gói và mô-đun
- Chuỗi tài liệu mô-đun giống với chuỗi tài liệu lớp. Thay vì các lớp và phương thức lớp được ghi lại, giờ đây nó là mô-đun và bất kỳ chức năng nào được tìm thấy trong
- Chuỗi tài liệu gói nên liệt kê các mô-đun và gói con được xuất bởi gói
- Các chuỗi tài liệu này phải được đặt ở đầu __init__ của gói. tệp py
- Như đã nêu trước đó, Mô-đun/gói Tài liệu này có thể được truy cập bằng cách sử dụng lệnh help[] đơn giản
3. Tập lệnh hoặc Tài liệu Chức năng
- Các Docstrings này được cung cấp cho các chức năng đơn giản độc lập và thực hiện một nhiệm vụ nhất định
- Tài liệu tập lệnh trước tiên phải đưa ra một mô tả ngắn về chức năng của tập lệnh. Tiếp theo là tất cả các loại đầu vào và tham số, nếu có, sau đó nêu rõ loại trả về của tập lệnh cụ thể đó
[Bán tại. [def hello_world[arg]
“””
Tóm lược
Đưa ra một mô tả ngắn gọn và súc tích về kịch bản ở đây
Thông số
arg [int]. Nói về lập luận ở đây
trả lại
int. Nói về loại giá trị trả về ở đây
“””
đối số trả về]]
Các định dạng khác nhau của Docstrings
Bây giờ chúng ta hãy xem các định dạng khác nhau của Tài liệu có sẵn để sử dụng, phần chính của Hướng dẫn Nhận xét và Tài liệu
Vì vậy, bạn có thể quyết định cái nào bạn muốn sử dụng trong mã của mình. Nhưng hãy nhớ sử dụng cùng một định dạng Chuỗi tài liệu cho toàn bộ mã vì nó có thể gây nhầm lẫn cho người đọc
Trước tiên, chúng ta hãy xem định dạng Chuỗi tài liệu được sử dụng phổ biến nhất mà tôi. e. , định dạng Nhân sư
1. định dạng nhân sư
- Sphinx rất dễ hiểu và ban đầu được tạo riêng cho Tài liệu Python
- Sphinx sử dụng Văn bản được cấu trúc lại, Văn bản được cấu trúc lại là ngôn ngữ đánh dấu nhẹ được sử dụng trong trình tạo trang web tĩnh như Sphinx. Nó chứa các công cụ mạnh mẽ để đánh dấu ngữ nghĩa, tái sử dụng nội dung và bộ lọc nội dung cho các loại đầu ra khác nhau.
[Ví dụ về định dạng Nhân sư]
- Một cặp param và type tùy chọn chỉ thị phải .
- Tùy chọn tăng được sử dụng để mô tả bất kỳ lỗi nào do mã đưa ra,
- Trong khi các tùy chọn return và rtype được sử dụng để .
Bây giờ chúng ta đã hiểu hoạt động của Định dạng chuỗi tài liệu Sphinx,
Mọi định dạng khác chỉ là một phiên bản tương tự hoặc có nguồn gốc từ định dạng Nhân sư làm cho các định dạng sau dễ hiểu hơn nhiều
class Bank[object]: ''' The Bank object contains info about all the accounts :param arg: The arg is used for ... :type arg: str :param `*args`: The variable arguments are used for ... :param `**kwargs`: The keyword arguments are used for ... :ivar arg: This is where we store arg :vartype arg: str ''' def __init__[self, arg, *args, **kwargs]: self.arg = arg def acc[self, Money_withdrawn, Total_Money]: '''We can't Withdraw Money without it being in the bank :param Money_withdrawn: The amount of money withdrawn :type amount: float :param Total_Money: Total Money in the account :type amount: float :raises: :class:`RuntimeError`: Amount Withdrawn greater than Total_Money :returns: Remaining Money :rtype: float ''' pass
2. Google Tài liệu
- Google Style dễ sử dụng và trực quan hơn. Được sử dụng cho dạng tài liệu ngắn hơn
- Định dạng Google Docstring đôi khi có vấn đề với các mô tả nhiều dòng vì chúng có thể trông lộn xộn
- Định dạng này cũng được coi là tốt hơn định dạng Sphinx
class Bank[object]: ''' The Bank object contains info about all the accounts Args: arg [str]: The arg is used for... *args: The variable arguments are used for... **kwargs: The keyword arguments are used for... Attributes: arg [str]: This is where we store arg, ''' def __init__[self, arg, *args, **kwargs]: self.arg = arg def acc[self, Money_withdrawn, Total_Money]: '''We can't Withdraw Money without it being in the bank Args: Money_withdrawn [float]: The amount of Money Withdrawn Total_money [float]: Total Money in the account Raises: RuntimeError: Amount Withdrawn greater than Total_Money Returns: float: Remaining Money ''' pass
3. Kiểu dáng gọn gàng
- Numpy Style là một loại định dạng chi tiết hơn nhiều
- Đó là một lựa chọn tuyệt vời nếu bạn muốn làm tài liệu chi tiết, tôi. e. , tài liệu mở rộng về tất cả các chức năng và tham số
- Do kiểu Numpy này cũng dài nhất trong số các định dạng khác hiện có
[Ví dụ về định dạng NumPy]
class Bank[object]: ''' The Bank object contains info about all the accounts Parameters ---------- arg : str The arg is used for ... *args The variable arguments are used for ... **kwargs The keyword arguments are used for ... Attributes ---------- arg : str This is where we store arg, ''' def __init__[self, arg, *args, **kwargs]: self.arg = arg def acc[self, Money_withdrawn, Total_Money]: '''We can't Withdraw Money without it being in the bank Parameters ---------- Money_withdrawn : float The amount of money withdrawn Total_Money : float Total Money in the account Raises ------ RuntimeError Amount Withdrawn greater than Total_Money Returns ------- float Remaining Money ''' pass
Kết luận về Nhận xét và Chuỗi tài liệu trong Hướng dẫn Python
- Và chúng tôi đã có nó;
- Chúng tôi đã học được sự khác biệt chính giữa Nhận xét và Chuỗi tài liệu và cách chúng tôi quyết định sử dụng cái nào trong một trường hợp nhất định
- Chúng tôi cũng đã tìm hiểu về các loại định dạng Docstring khác nhau mà bạn có thể sử dụng tùy thuộc vào loại tài liệu bạn muốn xây dựng
- Với kiến thức lão luyện này, bạn có thể dễ dàng thêm nhận xét và Tài liệu vào mã của mình trong khi đưa ra lời giải thích cho người đọc. Bây giờ, tại sao không thử nó một mình. Theo dõi chúng tôi trên Reddit
Việc sử dụng nhận xét và ví dụ là gì?
Nhận xét về cơ bản là ghi chú văn bản giải thích về mã nguồn . Hơn nữa, chúng hoạt động như tài liệu trong mã nguồn. Chúng tôi bao gồm các bình luận để tăng khả năng đọc của chương trình. Bên cạnh đó, các chú thích giúp lập trình viên dễ dàng ghi nhớ những điều phức tạp được thêm vào mã.Một ví dụ về nhận xét trong lập trình là gì?
Nhận xét một dòng bắt đầu bằng hai dấu gạch chéo lên [//]. // Đây là nhận xét.