Định nghĩa nhận xét Python

Tóm lược. trong hướng dẫn này, bạn sẽ học cách thêm nhận xét vào mã của mình. Và bạn sẽ tìm hiểu các loại nhận xét Python khác nhau bao gồm nhận xét khối, nhận xét nội tuyến và chuỗi tài liệu

Giới thiệu về bình luận Python

Đôi khi, bạn muốn ghi lại mã mà bạn viết. Ví dụ: bạn có thể muốn lưu ý lý do tại sao một đoạn mã hoạt động. Để làm điều đó, bạn sử dụng các ý kiến

Thông thường, bạn sử dụng nhận xét để giải thích các công thức, thuật toán và logic kinh doanh phức tạp

Khi thực thi một chương trình, trình thông dịch Python sẽ bỏ qua các chú thích và chỉ diễn giải mã

Python cung cấp ba loại nhận xét bao gồm nhận xét khối, nhận xét nội tuyến và chuỗi tài liệu

Bình luận khối Python

Một bình luận khối giải thích mã theo sau nó. Thông thường, bạn thụt lề một khối nhận xét ở cùng cấp với khối mã

Để tạo một bình luận khối, bạn bắt đầu với một dấu thăng đơn (

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

# increase price by 5%
price = price * 1.05
Code language: Python (python)

Nhận xét nội tuyến Python

Khi bạn đặt một nhận xét trên cùng một dòng với một câu lệnh, bạn sẽ có một nhận xét nội tuyến

Tương tự như nhận xét khối, nhận xét nội tuyến bắt đầu bằng một dấu thăng đơn (

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Ví dụ sau minh họa một nhận xét nội tuyến

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

tài liệu Python

Chuỗi tài liệu là một chuỗi ký tự mà bạn đặt làm dòng đầu tiên trong một khối mã, ví dụ: một hàm

Không giống như một nhận xét thông thường, một chuỗi tài liệu có thể được truy cập trong thời gian chạy bằng cách sử dụng thuộc tính 

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Thông thường, bạn sử dụng chuỗi tài liệu để tự động tạo tài liệu mã

Chuỗi tài liệu được gọi là docstrings

Về mặt kỹ thuật, docstrings không phải là ý kiến. Họ tạo các biến ẩn danh tham chiếu các chuỗi. Ngoài ra, chúng không bị trình thông dịch Python bỏ qua

Python cung cấp hai loại docstrings. tài liệu một dòng và tài liệu nhiều dòng

1) Tài liệu một dòng

Đúng như tên gọi của nó, một chuỗi tài liệu một dòng phù hợp với một dòng. Chuỗi tài liệu một dòng bắt đầu bằng ba dấu ngoặc kép (

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Ví dụ sau minh họa chuỗi tài liệu một dòng trong hàm

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

def quicksort():
""" sort the list using quicksort algorithm """
...
Code language: Python (python)

2) Tài liệu nhiều dòng

Không giống như chuỗi tài liệu một dòng, chuỗi tài liệu nhiều dòng có thể trải rộng trên nhiều dòng. Một chuỗi tài liệu nhiều dòng cũng bắt đầu bằng ba dấu ngoặc kép (_______20) và kết thúc bằng ba dấu ngoặc kép (

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Ví dụ sau đây cho bạn thấy cách sử dụng chuỗi tài liệu nhiều dòng

def increase(salary, percentage, rating):
    """ increase salary base on rating and percentage
    rating 1 - 2 no increase
    rating 3 - 4 increase 5%
    rating 4 - 6 increase 10%
    """
Code language: Python (python)

Nhận xét nhiều dòng Python

Python không hỗ trợ bình luận nhiều dòng

Tuy nhiên, bạn có thể sử dụng chuỗi tài liệu nhiều dòng làm nhận xét nhiều dòng. Guido van Rossum, người tạo ra Python, cũng khuyến nghị điều này

Đó là một thực hành tốt để giữ cho nhận xét của bạn rõ ràng, ngắn gọn và giải thích. Mục tiêu cuối cùng là tiết kiệm thời gian và năng lượng cho bạn và những nhà phát triển khác, những người sẽ làm việc với mã sau này

Nhận xét là một phần không thể thiếu của bất kỳ chương trình nào. Mọi ngôn ngữ lập trình đều cung cấp một cách để thêm nhận xét. Hệ thống bình luận Python rất dễ dàng. Trong hướng dẫn này, chúng ta sẽ tìm hiểu về comment trong Python. Họ cung cấp thông tin hữu ích về mã cho các nhà phát triển

Làm thế nào để viết bình luận trong Python?

• Nhận xét Python bắt đầu bằng ký tự # và kéo dài đến cuối dòng
• Chúng ta có thể bắt đầu nhận xét từ đầu dòng, sau một số khoảng trắng hoặc mã
• Nếu ký tự băm xuất hiện trong một chuỗi ký tự, thì đó là một phần của chuỗi

Ví dụ về nhận xét Python

Chúng ta có thể thêm nhận xét cho các biến, hàm và lớp. Chúng được sử dụng để cung cấp mục đích sử dụng của một phần mã. Hãy xem xét một số ví dụ về nhận xét trong Python

1. Nhận xét cho các biến

name = "Pankaj"  # employee name
id = 100  # employee id

data = "#123"  # this is comment, data contains # and that is not part of the comment.

2. Nhận xét cho chức năng

# This function adds the two numbers
def add(x, y):
    return x+y

3. Nhận xét cho lớp học

# This class provides utility functions to work with Strings
class StringUtils:

    def reverse(s):
        return ''.join(reversed(s))

Khối nhận xét Python hoặc nhận xét nhiều dòng

Đôi khi không thể có nhận xét trong một dòng. Trong trường hợp này, chúng ta có thể tạo khối bình luận hoặc chia bình luận thành nhiều dòng. Chúng tôi phải thêm tiền tố vào mỗi dòng bằng hàm băm (#) để viết nhận xét nhiều dòng

________số 8

Sử dụng Chuỗi tài liệu Python làm Nhận xét nhiều dòng

Các chuỗi tài liệu Python (Docstring) được sử dụng để cung cấp tài liệu cho các hàm, lớp và mô-đun. Chúng được xác định giữa một cặp ba dấu ngoặc kép (“””). Chúng phải được định nghĩa ngay bên dưới khai báo hàm hoặc lớp

Hãy xem nhanh một số ví dụ về chuỗi tài liệu Python

def foo():
    """The foo() function needs to be implemented.
    Currently, this function does nothing."""
    pass


class Data:
    """ This class is used to hold Data objects information."""

Chúng ta có thể truy cập chuỗi tài liệu của một thực thể bằng thuộc tính

# This function adds the two numbers
def add(x, y):
    return x+y

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Bạn có nên sử dụng Docstring để chỉ định các nhận xét nhiều dòng dài không?

Mục đích của chuỗi tài liệu Python là cung cấp tài liệu. Đôi khi bạn sẽ nhận thấy rằng nó bị lạm dụng để cung cấp các nhận xét dài. Tuy nhiên, đó không phải là cách tiếp cận được đề xuất. Nếu bạn muốn bình luận trải rộng thành nhiều dòng, chỉ cần đặt trước mỗi dòng một ký tự băm

Chuỗi nhiều dòng Python dưới dạng nhận xét nhiều dòng

Chúng tôi cũng có thể sử dụng các chuỗi nhiều dòng làm nhận xét nhiều dòng. Theo tweet của Guido này, họ không tạo mã

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Tuy nhiên, nó có thể dẫn đến các vấn đề với vết lõm. Nó cũng khó hiểu tại sao một chuỗi lại có trong mã mà không được sử dụng. Vì vậy, tốt hơn hết là bạn nên tuân theo các nhận xét nhiều dòng thông thường bằng cách sử dụng các ký tự băm

Thực tiễn tốt nhất về bình luận Python

• Luôn cung cấp các nhận xét có ý nghĩa để chỉ định việc sử dụng thực thể
• Tốt hơn là chia bình luận dài thành nhiều dòng
• Đừng thô lỗ trong các bình luận
• Giữ ý kiến ​​​​đến điểm. Không ai muốn đọc một cuốn tiểu thuyết trong các bình luận mã
• Tránh những bình luận vô ích không cung cấp bất kỳ thông tin hữu ích nào. Dưới đây là một số ví dụ về nhận xét vô ích

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

• Đôi khi bình luận là không cần thiết. Có tên riêng của thực thể là đủ tốt. Hãy xem một ví dụ về kịch bản này

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

• Nó luôn luôn là một ý tưởng tốt để có một hệ thống bình luận tại chỗ. Khi làm việc với nhiều thành viên trong nhóm và nhiều dự án trong một tổ chức, nên sử dụng chính sách nhận xét. Ví dụ: bạn có thể xác định chính sách nhận xét như thế này

salary = salary * 1.02   # increase salary by 2%
Code language: Python (python)

Phím tắt bình luận Python để bình luận một khối

Nếu bạn đang làm việc với Python IDE hoặc Jupyter Notebook, bạn có thể sử dụng lối tắt để nhận xét một khối mã

• Phím tắt nhận xét macOS – Chọn các dòng bạn muốn nhận xét và nhấn Command +/ và nó sẽ tự động thêm # ở đầu mỗi dòng để biến chúng thành một khối nhận xét. Nếu đó là một dòng trống, nó sẽ thêm # ở đầu dòng và bạn có thể viết bình luận
• Windows và Linux Comment Shortcut – Sử dụng Ctrl+/ làm phím tắt để biến một khối mã thành một bình luận

Tóm lược

• Hệ thống bình luận Python rất đơn giản và luôn bắt đầu bằng #
• Chuỗi tài liệu Python được sử dụng cho tài liệu. Bạn không nên lạm dụng nó cho các bình luận nhiều dòng
• Bắt đầu mọi dòng với ký tự băm cho nhận xét nhiều dòng
• Thực hiện theo các phương pháp hay nhất để thêm nhận xét vào chương trình
• Có chính sách bình luận tại chỗ luôn là một ý kiến ​​hay khi làm việc với nhiều thành viên trong nhóm

Cái gì tiếp theo?

Chúng tôi đã tham khảo rất nhiều chủ đề trong hướng dẫn này, bạn nên đọc các hướng dẫn sau để hiểu thêm về chúng