Nói một cách đơn giản, nhận xét là một mục được thêm vào mã nguồn để cho phép hiểu sâu hơn về logic đằng sau lý do tại sao mã được viết theo cách của nó. Trong Python, ký hiệu ‘#’ hoặc pound được yêu cầu trước mỗi bình luận. Biểu tượng này cho phép trình thông dịch hoặc trình biên dịch Python bỏ qua văn bản theo.
Khi làm việc trong một cơ sở mã lớn, nhà phát triển có thể cần tham khảo lại thông tin trong nhận xét hàng tuần hoặc hàng tháng sau để đảm bảo rằng họ hiểu mục đích ban đầu của mã. Thông tin này cần thiết cho khía cạnh logic hình thức của ý tưởng ban đầu và là một tiêu chí thiết yếu khi làm việc với các nhà phát triển khác trong một dự án mở rộng.
Các nhà phát triển xem xét và/hoặc theo dõi để sửa đổi một phần mã thường dựa nhiều vào nhận xét để nhận ra và tuân theo quy trình suy nghĩ của nhà phát triển ban đầu. Bằng cách này, các nhà phát triển kế tiếp có thể thêm, chỉnh sửa hoặc sửa đổi chú thích để điều chỉnh cách hiểu hoặc lý luận của các bản cập nhật tiếp theo nếu mã thay đổi.
Thư viện Python mặc định yêu cầu các dòng mã không dài hơn 79 ký tự. Quy định này là khác nhau đối với bình luận, đó là 72 ký tự. Nếu một nhận xét vượt quá giới hạn chuỗi tài liệu 72 ký tự, nhà phát triển nên thêm dòng thứ hai bắt đầu bằng ký hiệu '#'. Thường cần nhiều hơn một dòng để giải thích lý do đằng sau cách thức hoặc lý do tại sao nhà phát triển viết mã
Khi bình luận được thêm vào, nó phải được viết thành câu hoàn chỉnh. Nó cũng nên thể hiện một cách ngắn gọn một ý tưởng đơn giản để giới hạn sự tập trung của lời giải thích chỉ vào phần mã yêu cầu làm rõ
Thông thường, một nhà phát triển nên viết hoa từ đầu tiên của nhận xét. Nếu nó được sử dụng làm định danh, thuật ngữ ban đầu phải bắt đầu bằng một chữ cái viết thường.
Nhận xét khối dòng đơn được đánh dấu bằng ký hiệu '#' ở đầu dòng. Điều này có nghĩa là tất cả các ký tự sau ký hiệu # trên một dòng nhất định đều là một phần của nhận xét. Nhận xét kết thúc khi dòng kết thúc
#!/usr/bin/python3
# this is a single line comment describing the command below
commandLoại nhận xét khối đơn thứ hai là nhận xét nội tuyến. Nhận xét nội tuyến tồn tại trên cùng một dòng với một dòng mã. Thông thường, các nhận xét nội tuyến được phân tách bằng tối thiểu hai dấu cách từ một câu lệnh được lưu ý trong PEP 8 Python style guide. Sử dụng một khoảng trắng không được tán thành và bị coi là hình thức xấu.
#!/usr/bin/python3
for x in[1, 2, 3]: # This is an inline comment Python không sử dụng một tính năng cụ thể để tạo nhận xét nhiều dòng như trong ngôn ngữ Java hoặc C. Tuy nhiên điều này không có nghĩa là chúng ta không thể comment nhiều dòng trong Python. Có hai phương pháp chính để tạo nhiều dòng chú thích trong mã của chúng tôi.
chặn bình luận. Chúng ta có thể xâu chuỗi nhiều chú thích một dòng để tạo chú thích khối.
#!/usr/bin/python3
# This is
# a multi-line
# comment.
for x in[1, 2, 3]:Chúng tôi cũng có thể sử dụng dấu phân cách ở mỗi đầu của nhận xét để tạo nhận xét nhiều dòng. Dấu phân cách là ba ký hiệu trích dẫn kép ["""] hoặc ba ký hiệu trích dẫn đơn ['''] được xâu chuỗi lại với nhau ở mỗi đầu của nhận xét. Như đã thấy trong ví dụ bên dưới, văn bản sau dấu phân cách bắt đầu có thể nằm trên cùng một dòng nhưng dấu phân cách kết thúc nhận xét nhiều dòng phải nằm trên một dòng.
#!/usr/bin/python3
""" This is
a multi-line
comment as well!
"""Python cũng có một khái niệm tích hợp gọi là chuỗi tài liệu hoặc chuỗi tài liệu. Chuỗi tài liệu là một chuỗi ký tự được thụt lề và nằm dưới một hàm và giải thích chức năng của nó. Các chuỗi tài liệu này mô tả một hàm, lớp, mô-đun hoặc phương thức. Văn bản này được đưa vào dưới dạng nhận xét bên dưới mô-đun. Chúng là một phiên bản bình luận hợp lý và hữu ích hơn
Chúng ta phải biết nơi chúng ta đặt nhận xét trong mã của mình. Nếu một chuỗi nhận xét theo sau
- Quá gần sau một chức năng
- Định nghĩa của một lớp
- Khi bắt đầu một mô-đun
nó được đọc dưới dạng một chuỗi tài liệu; . Đoạn mã dưới đây cung cấp một ví dụ về chuỗi tài liệu. Lưu ý cách nhận xét bên dưới hàm result = a * b được thụt vào?
#!/usr/bin/python3
def stuff[a, b]:
result = a * b
"""
Below, we define the sum
of the result
to use in function x
"""
return resultCác chuỗi tài liệu cũng giúp liên kết và tạo tài liệu về một đối tượng khi sử dụng thuộc tính __doc__ trong hệ thống help[] tích hợp Python hoặc chức năng trợ giúp tương tác
Có hai loại docstrings
- Lót. Một chuỗi tài liệu nằm trên một dòng
- nhiều dòng. Các tài liệu bao gồm một dòng tóm tắt tương tự như một dòng lót, theo sau là một dòng trống. Một mô tả chi tiết hơn sau dòng trống
Đối với chuỗi tài liệu, luôn mở và đóng nhận xét bằng định dạng "ba trích dẫn kép" hoặc định dạng "ba trích dẫn đơn"
Đây là một ví dụ về chuỗi tài liệu một lớp.
#!/usr/bin/python3
for x in[1, 2, 3]:
""" This is a general for loop syntax """ Dưới đây là một ví dụ về chuỗi tài liệu nhiều dòng
#!/usr/bin/python3
def cars[GM, Ford, Chevy]:
""" This denotes the type and year of cars
GM 1992-2021
Ford 1992-2021
Chevy 1992-2021
""" Sự khác biệt sau đó là gì?
Vì vậy, sự khác biệt giữa các tài liệu và nhận xét nhiều dòng là gì?
Các tài liệu chủ yếu được sử dụng khi mô tả một chức năng hoặc cung cấp các gợi ý theo ngữ cảnh. Một chuỗi tài liệu được thụt vào và nằm bên dưới một hàm, đồng thời giải thích chức năng của hàm đó. Bản thân các nhận xét không được thụt lề và không cung cấp bất kỳ chức năng nào ngoài việc cung cấp thông tin hữu ích cho các nhà phát triển đang cố gắng hiểu logic mã. Nếu chúng ta không gán một chuỗi tài liệu cho một biến, nó sẽ hoạt động như một nhận xét
- Đảm bảo nhận xét càng ngắn gọn và mang tính mô tả càng tốt mà không làm mất ngữ cảnh
- Luôn sử dụng nhận xét để mô tả logic của mã chứ không phải cách mã hoạt động
- Hạn chế comment thừa. Không sử dụng lặp đi lặp lại cùng một nhận xét cho các chức năng có tên tương tự. Sử dụng quy ước đặt tên tốt hơn cho các chức năng giải quyết vấn đề này
Nhận xét là một phần không thể thiếu của mọi tập lệnh hoặc chương trình Python. Chúng mô tả chức năng, mục đích hoặc đầu ra dự kiến của một khối mã. Nhiều loại nhận xét có thể được sử dụng trong hầu hết mọi tình huống, tăng độ rõ ràng và chi tiết trong khối mã. Ngoài ra, các chuỗi tài liệu có thể được sử dụng làm nhận xét hoặc có thể tạo tài liệu về một đối tượng trong hệ thống trợ giúp tương tác Python. Nhận xét là một phần không thể thiếu của bất kỳ cơ sở mã nào và nên được sử dụng thường xuyên khi cần thiết. Chúng đặc biệt hữu ích khi giải thích logic tại sao mã tồn tại và lý do đằng sau sự hiện diện của nó. Nghĩ theo cách này. Nếu bạn viết một đoạn mã và quay lại sau sáu tháng và không hiểu nó làm gì hoặc tại sao nó được sử dụng, hãy viết bình luận cho nó