Bình luận trong Python là gì?

Lập trình phản ánh cách suy nghĩ của bạn để mô tả các bước đơn lẻ 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 được ý định mã của bạn sau này. Điều này cho phép bạn dễ dàng tìm ra lỗi hơn, sửa chúng, cải thiện mã sau này và cũng như sử dụng lại mã đó 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à phương pháp hay 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, rất nhanh. Trong bài viết này, chúng tôi sẽ giải thích các phương pháp nhận xét khác nhau mà Python hỗ trợ và cách sử dụng nó để tự động tạo tài liệu cho mã của bạn bằng cái gọi là chuỗi tài liệu cấp mô-đun

Bình luận cũng quan trọng nhưng vẫn có thể viết bình luận xấu. Chúng phải luôn ngắn gọn, đi thẳng vào vấn đề và bổ sung giá trị thông tin

Ví dụ, đây là một bình luận khá vô dụng

Thay vào đó, ví dụ tiếp theo hiển thị một nhận xét hữu ích hơn và đi kèm với việc đặt tên rõ ràng cho các biến

Có vô số kịch bản khác đảm bảo nhận xét. Đây chỉ là một ví dụ. Một nguyên tắc nhỏ là thêm nhận xét cho bất kỳ dòng mã nào (chẳng hạn như hiểu 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 phải học

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ý. Tuy nhiên, một ký tự băm trong một giá trị chuỗi không được coi 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 một dòng riêng, bên cạnh một câu lệnh và dưới dạng một khối nhận xét nhiều dòng

Trong các phần sau tôi sẽ mô tả từng loại nhận xét

Nhận xét như vậy bắt đầu bằng ký tự băm (______3) và theo sau là văn bản có giải thích thêm

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

Hướng dẫn về Phong cách cho Mã Python (PEP8) đề xuất ít hơn 79 ký tự trên mỗi dòng. Trên thực tế, 70 hoặc 72 ký tự trên mỗi dòng sẽ dễ đọc hơn và do đó được khuyến nghị. Nếu bình luận 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 rộng nó ra nhiều dòng

Như đã đề cập ở trên, toàn bộ khối nhận xét cũng được hiểu bởi Python. Những nhận xét 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à giải thích mọi thứ chi tiết hơn, thường là

Về mặt kỹ thuật, Python không hỗ trợ rõ ràng cho nhận xét nhiều dòng, vì vậy các tùy chọn sau đây được một số người coi là giải pháp thay thế, nhưng vẫn hoạt động cho mục đích nhận xét nhiều dòng

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

Phiên bản 2 đơn giản hơn phiên bản 1. Mục đích ban đầu của nó là sử dụng để tạo tài liệu (xem thêm về điều này bên dưới), nhưng nó cũng có thể được sử dụng cho nhận xét nhiều 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 dấu ngoặc kép đặc biệt (""") để hoạt động và không phải ký tự băm

Thực tế phổ biến

Việc bắt đầu một tệp Python với một vài dòng nhận xét là điều khá phổ biến. Những dòng này nêu thông tin 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 mã 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 bằng phần mô tả và theo sau là thông báo bản quyền có tên tôi và năm xuất bản mã. Bên dưới, 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 đó

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 bạn đã viết với các mô-đun, hàm, lớp và phương thức Python. Một chuỗi tài liệu được thêm dưới dạng nhận xét ngay bên dưới phần đầu của chức năng, mô-đun hoặc đối tượng và mô tả chức năng, mô-đun hoặc đối tượng đó làm gì. Dự kiến ​​​​sẽ tuân theo các quy tắc này

Hãy xem hướng dẫn thực hành, thực tế của chúng tôi để học Git, với các phương pháp hay nhất, tiêu chuẩn được ngành chấp nhận và bao gồm bảng gian lận. Dừng các lệnh Git trên Google và thực sự tìm hiểu nó

• Một chuỗi tài liệu là một dòng hoặc một nhận xét nhiều 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 là một dòng trống theo sau

• Bắt đầu chuỗi tài liệu bằng chữ in hoa và kết thúc bằng dấu chấm

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

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 của Python, chuỗi tài liệu sau đó được cung cấp thông qua thuộc tính __doc__

>>> 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ừ chuỗi 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 chúng trong bài viết tiếp theo

Phần 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 lắm và bạn chỉ cần sức mạnh của sự bền bỉ. Nó giúp tất cả chúng tôi đang cố gắng hiểu mã của bạn, bao gồm cả chính bạn khi bạn xem lại mã của mình sau này. Chúng tôi hy vọng rằng lời khuyên mà chúng tôi đã cung cấp cho bạn ở đây sẽ giúp bạn dễ dàng tạo nhận xét và tài liệu tốt hơn trong mã của mình

Sự nhìn nhận

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

/* trong Python là gì?

Chức năng bình luận là gì?