Cách Viết Chú Thích Trong Python để Tối ưu Code Dễ đọc - Vietnix

Khi lập trình cho một dự án của khách hàng đôi khi cần đến nhiều lập trình viên, ý định của các lập trình viên sẽ không giống nhau trong từng đoạn code. Do đó, để các lập trình viên nắm rõ được ý định của những đoạn code phức tạp cần có những chú thích cụ thể. Bài viết này Vietnix sẽ hướng dẫn bạn các cách viết chú thích trong Python để đội ngũ hoặc người tiếp nhận khác có thể hiểu dự án hơn.

1. Giới thiệu về Chú thích trong Python
2. Cú pháp để viết chú thích, Comment trong Python
   1. Ghi chú trong Python ở đầu dòng
   2. Các Block Comment – chú thích nhiều dòng
   3. Inline Comments – Chú thích trên cùng dòng lệnh
3. Comment out code để thử nghiệm
4. Kết luận

Giới thiệu về Chú thích trong Python

Comment trong Python là những chú thích trong chương trình máy tính bị trình biên dịch và trình thông dịch bỏ qua. Sử dụng những chú thích này trong các chương trình có thể làm cho code dễ đọc hơn. Vì nó cung cấp một số thông tin hoặc giải thích mỗi phần của chương trình đang thực hiện.

Tùy thuộc vào mục đích chương trình của bạn, các chú thích python có thể dùng như ghi chú cho chính bạn hoặc là nhắc nhở. Hoặc là chúng có thể được viết với mục đích để các lập trình viên khác có thể hiểu được ngôn ngữ lập trình của bạn đang làm gì.

Nói chung, bạn nên viết chú thích code khi đang viết hoặc cập nhật một chương trình. Vì sau này bạn sẽ rất dễ quên và comment sẽ rất hữu ích để nhắc nhở lại cho bạn điều đó.

Bạn cũng có thể tham khảo thêm về hướng dẫn thiết lập môi trường lập trình và cài đặt Python 3 trên Ubuntu 20.04 cũng như cách chuyển đổi phong cách nghệ thuật hình ảnh sử dụng Neural Style Transfer với Python 3 và PyTorch hiện đã có trên website Vietnix để có thêm nhiều tùy chọn kiến thức cho bản thân.

Cú pháp để viết chú thích, Comment trong Python

Có nhiều các viết chú thích trong Python. Tùy độ phức tạp của đoạn code mà người viết có thể áp dụng các cách ghi chú trong Python ỏe đầu đoạn code, chú thích nhiều dòng và chú thích ngay trên chính dòng code đó.

Ghi chú trong Python ở đầu dòng

Chú thích Python bắt đầu bằng dấu # và ký tự khoảng trắng. Bạn có thể viết chú thích sau dấu # cho đến khi bắt đầu một dòng mới. Python sẽ không tính chú thích này khi thông dịch.

Thông thường thì comment sẽ trông như sau:

# This is a comment

Bởi vì comment python sẽ không được thực thi. Khi chạy chương trình, bạn sẽ không thấy bất kỳ dấu hiệu nào về comment ở đó. Comment nằm trong source code để con người đọc, không phải để máy tính thực thi.

Trong câu “Hello, World!”, một comment có thể trông như sau:

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

Vòng lặp for lặp qua một danh sách các comment trông giống như sau:

# 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)

Chú thích phải được thực hiện ở cùng một mức độ thụt lề như code. Nghĩa là, một hàm nếu không có thụt lề thì chú thích sẽ không có thụt lề.

Ví dụ: đây là cách hàm again() nhận được comment, với các comment theo sau mỗi mức thụt lề của code:

... # 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()

Chú thích trong Python được thực hiện để giúp các lập trình viên, cho dù đó là người mới hoặc là một lập trình viên lâu lắm. Nếu các chú thích python không thể được duy trì và cập nhật đúng cách cùng với code base, tốt hơn là không nên bao gồm chú thích vì nó sẽ mâu thuẫn với các code.

Các Block Comment – chú thích nhiều dòng

Block Comment có thể được sử dụng để giải thích code hoặc code phức tạp. Các chú thích dạng dài hơn này áp dụng cho một số hoặc tất các code theo sau và nó cũng được thụt lề cùng cấp với code.

Trong Block Comment, mỗi dòng bằng đầu bằng dầu (#) và một khoảng trắng. Nếu bạn cần sử dụng nhiều hơn một đoạn văn, chúng nên được phân tách bằng một dòng và mỗi dòng có chứa một dấu (#).

Dưới đây là một ví dụ về một Block Comment xác định những gì đang xảy ra trong hàm main():

# 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" ) ...

Có một các chú thích nhiều dòng khác đó là sử dụng ba dấu nháy đơn (''') hoặc ba dấu nháy kép (""").

Ví dụ với ba dấu nháy đơn:

'''Bạn có thê viết chú thích nhiều dòng tại đây để giải thích các đoạn code phức tạp cho người dùng hoặc lập trình viên khác nắm bắt được'''

Ví dụ đối với ba dấu nháy kép:

"""Đây là ví dụ của https://vietnix.vn/, ba dấu nháy kép có thể giúp bạn ghi đoạn chú thích nhiều dòng để giải thích đoạn code"

Block Comment thường được sử dụng khi các hoạt động kém đơn giản và yêu cầu giải thích kỹ lưỡng. Bạn nên cố gắng tránh sử dụng quá nhiều comment python và nên có xu hướng tin tưởng các lập trình viên hiểu Python. Trừ khi bạn đang viết cho một đối tượng cụ thể.

Inline Comments – Chú thích trên cùng dòng lệnh

Inline Comment xảy ra trên cùng một dòng của một câu lệnh, sau code. Giống như các chú thích python khác, chúng bắt đầu bằng một dấu (#) và một khoảng trắng duy nhất.

Thông thường, Inline Comment sẽ trông như sau:

[code] # Inline comment about the code

Inline Comment nên được sử dụng một cách vừa phải. Nhưng nó sẽ có thể hiệu quả để giải thích các phần phức tạp hoặc không rõ của code. 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 code bạn đang viết. Hoặc nếu bạn đang cộng tác với một người mà bạn biết và họ không quen thuộc các khía cạnh của code.

Ví dụ: Nếu bạn không sử dụng nhiều toán học trong các chương trình Python và bạn hoặc cộng tác viên của bạn có thể không biết rằng đây là số phức. Vì vậy bạn có thể muốn bao gồm một Inline Comment về điều đó:

z = 2.5 + 3j # Create a complex number

Inline Comment cũng có thể được sử dụng để giải thích lý do việc đang làm hoặc một số thông tin bổ sung như:

x = 8 # Initialize x with an arbitrary number

Các Comment Python đưa ra theo dòng chỉ nên được sử dụng khi cần thiết và khi chúng có thể cung cấp hướng dẫn hữu ích cho người dùng đọc chương trình.

Comment out code để thử nghiệm

Ngoài việc sử dụng chú thích python như một cách để ghi lại code, dấu (#) cũng có thể được sử dụng để comment out code mà bạn không muốn thực thi trong khi bạn đang thử nghiệm hoặc debug một chương trình bạn hiện đang tạo. Đó là, khi bạn gặp lỗi sau khi triển khai các dòng code mới, bạn có thể muốn chú thích một vài lỗi trong số đó để xem liệu bạn có thể khắc phục sự cố chính xác hay không.

Sử dụng dấu (#) cũng có thể cho phép bạn thử các lựa chọn thay thế khác trong khi bạn đang xác định cách thiết lập code của mình. Ví dụ: bạn có thể quyết định sử dụng vòng lặp while hoặc vòng lặp for trong Python và có thể comment out cái nào tốt nhất.

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))

Comment out code bằng dầu (#) 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 lỗi thông qua chú thích Python một cách có hệ thống và các phần đang chạy của chương trình.

Kết luận

Sử dụng Chú thích trong Python giúp làm cho chương trình của bạn dễ đọc hơn đối với con người và bao gồm bản thân bạn trong tương lai. Chúc bạn thành công!!!