Cách viết nhận xét bằng Python 3

Giới thiệu

Nhận xét là các dòng tồn tại trong các chương trình máy tính bị bỏ qua bởi trình biên dịch và trình thông dịch. Bao gồm các chú thích trong các chương trình làm cho mã dễ đọc hơn đối với con người vì nó cung cấp một số thông tin hoặc giải thích về từng phần của chương trình đang làm.

Tùy thuộc vào mục đích của chương trình, nhận xét có thể đóng vai trò là ghi chú cho chính bạn hoặc lời nhắc hoặc có thể được viết với ý định của các lập trình viên khác có thể hiểu mã của bạn đang làm gì.

Nói chung, bạn nên viết nhận xét trong khi viết hoặc cập nhật chương trình vì dễ dàng quên quy trình suy nghĩ của bạn sau này và các nhận xét được viết sau này có thể ít hữu ích hơn trong thời gian dài.

Cú pháp nhận xét

Nhận xét bằng Python bắt đầu bằng dấu băm (#) và ký tự trắng và tiếp tục đến cuối dòng.

Nói chung, nhận xét sẽ trông giống như sau:

# This is a comment

Vì các bình luận không thực hiện, khi bạn chạy một chương trình, bạn sẽ không thấy bất kỳ dấu hiệu nào của chú thích ở đó. Nhận xét nằm trong mã nguồn để con người đọc, không phải cho máy tính để thực thi.

Trong một chương trình “Hello, World!”, Nhận xét có thể trông giống như sau:

hello.py

# Print “Hello, World!” to console
print("Hello, World!")

Trong một for vòng lặp lặp lại qua danh sách, nhận xét có thể trông giống như sau:

sharks.py

# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

Nhận xét phải được thực hiện tại cùng một thụt lề như mã mà nó đang nhận xét. Đó là một chức năng độ nét không có thụt lề sẽ có nhận xét không có thụt lề và mỗi mức thụt lề sau sẽ có các nhận xét phù hợp với mã mà nó đang nhận xét.

Ví dụ, đây là cách again() chức năng từ Làm thế nào để thực hiện một chương trình tính toán đơn giản trong Python 3 hướng dẫn được nhận xét, với nhận xét sau mỗi cấp độ thụt lề của mã:

calculator.py

...
# Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('
Do you want to calculate again?
Please type Y for YES or N for NO.
')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

Bình luận được thực hiện để giúp các lập trình viên, cho dù đó là lập trình viên ban đầu hoặc người khác sử dụng hoặc cộng tác trong dự án. Nếu nhận xét không thể được duy trì và cập nhật đúng cách cùng với cơ sở mã, tốt hơn là không bao gồm nhận xét thay vì viết nhận xét mâu thuẫn hoặc sẽ mâu thuẫn với mã.

Khi mã nhận xét, bạn nên tìm cách trả lời tại sao đằng sau mã như trái ngược với gì hoặc là làm sao. Trừ khi mã đặc biệt phức tạp, nhìn vào mã thường có thể cho biết mã đang làm gì hoặc nó đang hoạt động như thế nào.

Chặn nhận xét

Chặn nhận xét có thể được sử dụng để giải thích mã hoặc mã phức tạp hơn mà bạn không mong đợi người đọc quen thuộc. Các nhận xét dạng dài hơn này áp dụng cho một số hoặc tất cả mã sau, và cũng được thụt lề ở cùng cấp với mã.

Trong các chú thích khối, mỗi dòng bắt đầu bằng dấu băm và một dấu cách. Nếu bạn cần sử dụng nhiều hơn một đoạn, chúng phải được phân tách bằng một dòng có chứa một dấu băm duy nhất.

Dưới đây là ví dụ về nhận xét chặn xác định những gì đang xảy ra trong main() chức năng được xác định dưới đây:

# The main function will parse arguments via the parser variable.  These
# arguments will be defined by the user on the console.  This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not 
# correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

Chặn nhận xét thường được sử dụng khi các thao tác ít đơn giản hơn và do đó yêu cầu giải thích kỹ lưỡng. Bạn nên cố gắng tránh quá bình luận mã và nên có xu hướng tin tưởng các lập trình viên khác để hiểu Python trừ khi bạn đang viết cho một đối tượng cụ thể.

Nhận xét nội dòng

Nhận xét nội dòng xuất hiện trên cùng một dòng của một câu lệnh, tuân theo chính mã đó. Giống như các bình luận khác, chúng bắt đầu với một dấu băm và một ký tự trắng khoảng trắng.

Nói chung, nhận xét nội tuyến trông giống như sau:

[code]  # Inline comment about the code

Bình luận nội tuyến nên được sử dụng một cách tiết kiệm, nhưng có thể có hiệu quả để giải thích các phần khó hiểu hoặc không rõ ràng của mã. Chúng cũng có thể hữu ích nếu bạn nghĩ rằng bạn có thể không nhớ một dòng mã bạn đang viết trong tương lai hoặc nếu bạn đang cộng tác với người bạn biết có thể không quen thuộc với tất cả các khía cạnh của mã.

Ví dụ: nếu bạn không sử dụng nhiều môn Toán trong các chương trình Python của bạn, bạn hoặc cộng tác viên của bạn có thể không biết rằng những điều sau đây tạo ra một số phức tạp, vì vậy bạn có thể muốn bao gồm nhận xét nội tuyến về điều đó:

z = 2.5 + 3j  # Create a complex number

Các nhận xét nội tuyến cũng có thể được sử dụng để giải thích lý do đằng sau việc làm gì đó hoặc một số thông tin bổ sung, như sau:

x = 8  # Initialize x with an arbitrary number

Ý kiến ​​được thực hiện trong dòng nên được sử dụng chỉ khi cần thiết và khi họ có thể cung cấp hướng dẫn hữu ích cho người đọc chương trình.

Nhận xét ra mã để thử nghiệm

Ngoài việc sử dụng nhận xét làm cách để mã tài liệu, dấu băm cũng có thể được sử dụng để nhận xét mã mà bạn không muốn thực thi trong khi đang thử nghiệm hoặc gỡ lỗi chương trình bạn hiện đang tạo. Tức là, khi bạn gặp phải lỗi sau khi triển khai các dòng mã mới, bạn có thể muốn nhận xét một vài mã trong số đó để xem bạn có thể khắc phục sự cố chính xác không.

Sử dụng dấu băm cũng có thể cho phép bạn thử các lựa chọn thay thế trong khi bạn đang xác định cách thiết lập mã của mình. Ví dụ: bạn có thể quyết định sử dụng while vòng lặp hoặc một for loop trong một trò chơi Python, và có thể bình luận ra một hay khác trong khi kiểm tra và xác định cái nào có thể là tốt nhất:

guess.py

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

Nhận xét ra mã với dấu băm có thể cho phép bạn thử các phương pháp lập trình khác nhau cũng như giúp bạn tìm ra nguồn gốc của một lỗi thông qua hệ thống nhận xét và chạy các phần của chương trình.

Phần kết luận

Sử dụng các chú thích trong các chương trình Python của bạn sẽ giúp cho các chương trình của bạn dễ đọc hơn đối với con người, bao gồm cả bản thân tương lai của bạn. Việc đưa các nhận xét thích hợp có liên quan và hữu ích có thể giúp những người khác cộng tác với bạn dễ dàng hơn trong các dự án lập trình và làm cho giá trị mã của bạn rõ ràng hơn.

Từ đây, bạn có thể muốn đọc về Python Tài liệu trong PEP 257 để cung cấp cho bạn nhiều tài nguyên hơn để ghi lại đúng các dự án Python của bạn.