Hướng dẫn how comments are used in python? - làm thế nào bình luận được sử dụng trong python?

Lập trình phản ánh cách suy nghĩ của bạn để mô tả các bước duy nhất mà bạn đã thực hiện để giải quyết vấn đề bằng máy tính. 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 sau này về ý định của mã của bạn. Điều này cho phép bạn dễ dàng tìm thấy lỗi hơn, để khắc phục chúng, để cải thiện mã sau này và sử dụng lại nó trong các ứng dụng khác.

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à - 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à được coi là thực hành tốt cho các nhà phát triển. Không có bình luận, mọi thứ có thể trở nên khó hiểu, thực sự nhanh chóng. Trong bài viết này, chúng tôi sẽ giải thích các phương pháp khác nhau để nhận xét hỗ trợ Python và cách nó có thể được sử dụng để tự động tạo tài liệu cho mã của bạn bằng cách sử dụng các tài liệu cấp độ mô-đun.

Quan trọng như bình luận, vẫn có thể viết những bình luận xấu. Chúng phải luôn luôn ngắn, thẳng vào điểm và thêm giá trị thông tin.

Ví dụ, đây là một nhận xét khá vô dụng:

b = 56                       # assigning b a value of 56

Ví dụ tiếp theo cho thấy một nhận xét hữu ích hơn, thay vào đó, và đi cùng với việc đặt lại các biến tên rõ ràng:

salestax10 = 1.10            # defining a sales tax of 10%
salestax20 = 1.20            # defining a sales tax of 20%

Có vô số các kịch bản khác đảm bảo bình luận. Đây chỉ là một ví dụ. Một quy tắc tốt sẽ là thêm nhận xét cho bất kỳ dòng mã nào (như hiểu biết danh sách) hoặc phần mã có mục đích không rõ ràng. Điều này rất chủ quan, và thực sự là một kỹ năng cần được học.

Một nhận xét trong Python bắt đầu với ký tự băm, #, và mở rộng đến cuối dòng vật lý. Tuy nhiên, một ký tự băm trong một giá trị chuỗi không được xem là một nhận xét. Nói chính xác, một nhận xét có thể được viết theo ba cách - hoàn toàn trên dòng riêng của nó, bên cạnh một câu lệnh mã và như một khối nhận xét đa dòng.

Trong các phần sau, tôi sẽ mô tả từng loại bình luận.

Một nhận xét như vậy bắt đầu với một ký tự băm (#), và được theo sau bởi văn bản có chứa các giải thích thêm.

# defining the post code
postCode = 75000

Bạn cũng có thể viết một bình luận bên cạnh một câu lệnh mã. Ví dụ tiếp theo cho thấy rằng:

# define the general structure of the product with default values
product = {
    "productId": 0,          # product reference id, default: 0
    "description": "",       # item description, default: empty
    "categoryId": 0,         # item category, default: 0
    "price": 0.00            # price, default: 0.00
}

Hướng dẫn kiểu cho mã Python (PEP8) khuyến nghị ít hơn 79 ký tự mỗi dòng. Trong thực tế, 70 hoặc 72 ký tự trên mỗi dòng dễ đọc hơn và do đó được khuyến nghị. Nếu nhận xét của bạn đang tiếp cận hoặc vượt quá độ dài này thì bạn sẽ muốn trải nó ra trên nhiều dòng.

Như đã đề cập ở trên, toàn bộ khối bình luận cũng được Python hiểu. Những bình luận này đóng vai trò là tài liệu nội tuyến cho những người khác đọc mã của bạn và thường giải thích mọi thứ chi tiết hơn, thường là.

Về mặt kỹ thuật, Python không có sự hỗ trợ rõ ràng cho các nhận xét đa dòng, vì vậy các tùy chọn sau được coi là một cách giải quyết của một số người, nhưng vẫn hoạt động cho mục đích của các bình luận đa dòng.

Phiên bản 1 kết hợp các nhận xét một dòng như sau:

# LinuxThingy version 1.6.5
#
# Parameters:
#
# -t (--text): show the text interface
# -h (--help): display this help

Phiên bản 2 đơn giản hơn phiên bản 1. Ban đầu, nó được dự định sẽ được sử dụng để tạo tài liệu (xem thêm về điều này dưới đây), nhưng nó cũng có thể được sử dụng cho các nhận xét đa dòng.

"""
LinuxThingy version 1.6.5

Parameters:

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

Lưu ý rằng phiên bản sau cần được đặt trong các dấu ngoặc kép đặc biệt (

salestax10 = 1.10            # defining a sales tax of 10%
salestax20 = 1.20            # defining a sales tax of 20%

1) để hoạt động và không phải các ký tự băm.

Thực tế phổ biến

Nó là khá phổ biến để bắt đầu một tệp Python với một vài dòng bình luận. Các dòng này thông tin trạng thái liên quan đến dự án, mục đích của tệp, lập trình viên đã phát triển nó hoặc đã làm việc với nó và giấy phép phần mềm được sử dụng cho mã.

Đoạn trích này được lấy từ một trong những ví dụ tôi sử dụng cho mục đích đào tạo. Nhận xét bắt đầu với mô tả, và được theo sau bởi thông báo bản quyền với tên của tôi và năm xuất bản mã. Dưới đây bạn sẽ thấy rằng mã được cấp phép theo Giấy phép Công cộng GNU (GPL). Để liên hệ với tôi địa chỉ email của tôi cũng được thêm vào đó.

# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
#
# (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email [email protected]
# -----------------------------------------------------------

Python có một khái niệm tích hợp gọi là DocStrings, đây là một cách tuyệt vời để liên kết tài liệu mà bạn đã viết với các mô-đun, chức năng, lớp học và phương pháp Python. Một DocString được thêm vào như một nhận xét ngay bên dưới hàm, mô -đun hoặc đầu đối tượng và mô tả những gì hàm, mô -đun hoặc đối tượng làm gì. Dự kiến ​​sẽ tuân theo các quy tắc sau:

Kiểm tra hướng dẫn thực hành của chúng tôi, thực tế để học Git, với các thực hành tốt nhất, các tiêu chuẩn được công nghiệp chấp nhận và bao gồm bảng gian lận. Ngừng các lệnh git googling và thực sự tìm hiểu nó!

• Một DocString là một dòng duy nhất hoặc một nhận xét đa dòng. Trong trường hợp sau, dòng đầu tiên là một mô tả ngắn và sau dòng đầu tiên, một dòng trống theo sau.

• Bắt đầu tài liệu bằng một chữ cái viết hoa, và kết thúc nó bằng một khoảng thời gian.

Đây là một ví dụ cơ bản về những gì nó trông như thế nào:

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

Trong hệ thống trợ giúp tương tác Python, DocString sau đó được cung cấp thông qua thuộc tính

salestax10 = 1.10            # defining a sales tax of 10%
salestax20 = 1.20            # defining a sales tax of 20%

2.

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

Có một số công cụ tự động tạo tài liệu từ các tài liệu, chẳng hạn như Doxygen, Pydoc, PDOC và tiện ích mở rộng AutoDoc cho Sphinx.Chúng tôi sẽ giải thích cho bạn cách làm việc với họ trong một bài viết tiếp theo.

Sự kết luận

Viết nhận xét thích hợp trong mã Python của bạn không phức tạp và bạn chỉ cần sức mạnh của sức bền.Nó giúp tất cả chúng ta đang cố gắng hiểu mã của bạn, bao gồm cả bản thân khi bạn xem lại mã của mình vào một ngày sau đó.Chúng tôi hy vọng rằng lời khuyên mà chúng tôi đã đưa ra cho bạn ở đây giúp bạn dễ dàng tạo ra những nhận xét và tài liệu tốt hơn trong mã của bạn.

Sự nhìn nhận

Tác giả xin cảm ơn Zoleka Hofmann vì những bình luận phê bình của cô trong khi chuẩn bị bài viết này.