Làm thế nào để bạn nhận xét trong python?

Khi đọc mã của riêng bạn

Khách hàng A muốn triển khai vào phút cuối cho dịch vụ web của họ. Bạn đang ở trong một thời hạn chặt chẽ, vì vậy bạn quyết định làm cho nó hoạt động. Tất cả những thứ “bổ sung” đó—tài liệu, nhận xét phù hợp, v.v.—bạn sẽ bổ sung sau

Thời hạn đến và bạn triển khai dịch vụ đúng lúc. chà

Bạn ghi nhớ trong đầu để quay lại và cập nhật các nhận xét, nhưng trước khi bạn có thể đưa nó vào danh sách việc cần làm của mình, sếp của bạn đến với một dự án mới mà bạn cần bắt đầu ngay lập tức. Trong vòng vài ngày, bạn đã hoàn toàn quên mất rằng bạn phải quay lại và bình luận chính xác mã bạn đã viết cho Khách hàng A

Sáu tháng trôi qua nhanh và Khách hàng A cần một bản vá được tạo cho cùng dịch vụ đó để tuân thủ một số yêu cầu mới. Công việc của bạn là duy trì nó, vì bạn là người đã xây dựng nó ngay từ đầu. Bạn mở trình soạn thảo văn bản của mình và…

Bạn thậm chí đã viết gì?

Bạn dành hàng giờ để phân tích mã cũ của mình, nhưng bạn hoàn toàn bị lạc trong mớ hỗn độn. Vào thời điểm đó, bạn đang rất vội vàng nên đã không đặt tên đúng cho các biến của mình hoặc thậm chí không thiết lập các chức năng của mình theo quy trình kiểm soát phù hợp. Tệ nhất là bạn không có bất kỳ bình luận nào trong kịch bản để cho bạn biết cái gì

Các nhà phát triển luôn quên mã của họ làm gì, đặc biệt nếu nó được viết từ lâu hoặc chịu nhiều áp lực. Khi thời hạn đang đến rất nhanh và hàng giờ ngồi trước máy tính khiến đôi mắt đỏ ngầu và đôi bàn tay bị chuột rút, áp lực đó có thể được phản ánh dưới dạng mã lộn xộn hơn bình thường

Sau khi dự án được gửi, nhiều nhà phát triển đơn giản là quá mệt mỏi để quay lại và nhận xét mã của họ. Khi đến lúc xem lại nó sau đó, họ có thể dành hàng giờ để phân tích những gì họ đã viết

Viết bình luận khi bạn đi là một cách tuyệt vời để ngăn tình huống trên xảy ra. Hãy tử tế với Tương lai Bạn

Khi người khác đang đọc mã của bạn

Hãy tưởng tượng bạn là nhà phát triển duy nhất làm việc trên một dự án Django nhỏ. Bạn hiểu mã của mình khá rõ, vì vậy bạn không có xu hướng sử dụng nhận xét hoặc bất kỳ loại tài liệu nào khác và bạn thích nó theo cách đó. Nhận xét cần có thời gian để viết và duy trì, và bạn không nhìn thấy điểm

Vấn đề duy nhất là, vào cuối năm nay, “dự án Django nhỏ” của bạn đã trở thành một dự án “20.000 dòng mã” và người giám sát của bạn sẽ thuê thêm các nhà phát triển để giúp duy trì dự án đó.

Các nhà phát triển mới làm việc chăm chỉ để nhanh chóng bắt kịp tốc độ, nhưng trong vài ngày đầu tiên làm việc cùng nhau, bạn đã nhận ra rằng họ đang gặp một số rắc rối. Bạn đã sử dụng một số tên biến kỳ quặc và viết với cú pháp siêu ngắn gọn. Những người mới tuyển dụng dành nhiều thời gian để lướt qua từng dòng mã của bạn, cố gắng tìm ra cách tất cả hoạt động. Phải mất vài ngày trước khi họ thậm chí có thể giúp bạn duy trì nó

Sử dụng nhận xét xuyên suốt mã của bạn có thể giúp các nhà phát triển khác trong các tình huống như thế này. Nhận xét giúp các nhà phát triển khác lướt qua mã của bạn và hiểu được cách tất cả hoạt động rất nhanh. Bạn có thể giúp đảm bảo quá trình chuyển đổi suôn sẻ bằng cách chọn nhận xét mã của mình ngay từ đầu dự án

Khái niệm cơ bản về bình luận Python

Nhận xét dành cho nhà phát triển. Họ mô tả các phần của mã khi cần thiết để tạo điều kiện hiểu biết cho các lập trình viên, bao gồm cả bạn

Để viết bình luận bằng Python, chỉ cần đặt dấu thăng

print["This will run."]  # This won't run

# This is a comment

Python bỏ qua mọi thứ sau dấu thăng và cho đến cuối dòng. Bạn có thể chèn chúng vào bất cứ đâu trong mã của mình, thậm chí nội dòng với mã khác

print["This will run."]  # This won't run

Khi bạn chạy đoạn mã trên, bạn sẽ chỉ thấy đầu ra

print["This will run."]  # This won't run

Nhận xét phải ngắn gọn, hấp dẫn và đi thẳng vào vấn đề. Mặc dù PEP 8 khuyên nên giữ mã ở mức 79 ký tự trở xuống trên mỗi dòng, nhưng nó đề xuất tối đa 72 ký tự cho các nhận xét và chuỗi tài liệu nội tuyến. Nếu nhận xét của bạn sắp đạt hoặc vượt quá độ dài đó, thì bạn sẽ muốn trải dài nó ra nhiều dòng

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

Thật không may, Python không có cách viết nhận xét nhiều dòng như bạn có thể viết bằng các ngôn ngữ như C, Java và Go

# So you can't
just do this
in python

Trong ví dụ trên, dòng đầu tiên sẽ bị bỏ qua bởi chương trình, nhưng các dòng khác sẽ đưa ra Lỗi Cú pháp

Ngược lại, một ngôn ngữ như Java sẽ cho phép bạn trải một bình luận ra nhiều dòng khá dễ dàng

/* You can easily
write multiline
comments in Java */

Mọi thứ giữa

print["This will run."]  # This won't run

print["This will run."]  # This won't run

Mặc dù Python không có chức năng nhận xét nhiều dòng gốc nhưng bạn có thể tạo nhận xét nhiều dòng trong Python. Có hai cách đơn giản để làm như vậy

Cách đầu tiên đơn giản là nhấn phím

print["This will run."]  # This won't run

def multiline_example[]:
    # This is a pretty good example
    # of how you can spread comments
    # over multiple lines in Python

Mỗi dòng bắt đầu bằng dấu thăng sẽ bị chương trình bỏ qua

Một điều khác bạn có thể làm là sử dụng các chuỗi nhiều dòng bằng cách gói nhận xét của bạn bên trong một bộ ba dấu ngoặc kép

# This is a comment

Điều này giống như chú thích nhiều dòng trong Java, trong đó mọi thứ được đặt trong ba dấu ngoặc kép sẽ hoạt động như một chú thích

Mặc dù điều này cung cấp cho bạn chức năng nhiều dòng, nhưng về mặt kỹ thuật, đây không phải là nhận xét. Đó là một chuỗi không được gán cho bất kỳ biến nào, vì vậy nó không được gọi hoặc tham chiếu bởi chương trình của bạn. Tuy nhiên, vì nó sẽ bị bỏ qua trong thời gian chạy và sẽ không xuất hiện trong mã byte, nên nó có thể hoạt động như một nhận xét một cách hiệu quả. [Bạn có thể xem bài viết này để chứng minh rằng các chuỗi này sẽ không hiển thị trong mã byte. ]

Tuy nhiên, hãy cẩn thận nơi bạn đặt những “bình luận” nhiều dòng này. ” Tùy thuộc vào vị trí của chúng trong chương trình của bạn, chúng có thể biến thành chuỗi tài liệu, là những phần tài liệu được liên kết với một hàm hoặc phương thức. Nếu bạn bỏ qua một trong những kẻ xấu này ngay sau một định nghĩa hàm, thì những gì bạn dự định là một nhận xét sẽ được liên kết với đối tượng đó

Hãy cẩn thận khi bạn sử dụng những thứ này và khi nghi ngờ, chỉ cần đặt dấu thăng trên mỗi dòng tiếp theo. Nếu bạn muốn tìm hiểu thêm về chuỗi tài liệu và cách liên kết chúng với các mô-đun, lớp và những thứ tương tự, hãy xem hướng dẫn của chúng tôi về Lập tài liệu Mã Python

Phím tắt nhận xét Python

Có thể rất tẻ nhạt khi gõ tất cả các dấu băm đó mỗi khi bạn cần thêm nhận xét. Vậy bạn có thể làm gì để tăng tốc mọi thứ lên một chút?

Một trong những điều đầu tiên bạn có thể làm là sử dụng nhiều con trỏ. Đó chính xác là những gì nó nghe giống như. đặt nhiều hơn một con trỏ trên màn hình của bạn để hoàn thành một tác vụ. Chỉ cần giữ phím Ctrl hoặc Cmd trong khi nhấp chuột trái, .

Cách này hiệu quả nhất khi bạn cần bình luận cùng một nội dung ở nhiều nơi

Nếu bạn có một đoạn văn bản dài cần bình luận thì sao? . Nhấp vào từng dòng để bình luận có thể mất rất nhiều thời gian. Trong những trường hợp này, thay vào đó, bạn sẽ muốn chuyển đổi nhận xét. Chỉ cần chọn mã mong muốn và nhấn Ctrl + / trên PC hoặc . Cmd+/ on Mac:

Tất cả văn bản được đánh dấu sẽ được thêm vào trước một dấu thăng và bị chương trình bỏ qua

Nếu nhận xét của bạn trở nên quá khó sử dụng hoặc nhận xét trong tập lệnh bạn đang đọc thực sự dài, thì trình soạn thảo văn bản của bạn có thể cung cấp cho bạn tùy chọn thu gọn chúng bằng cách sử dụng mũi tên xuống nhỏ ở phía bên trái

Chỉ cần nhấp vào mũi tên để ẩn nhận xét. Điều này hoạt động tốt nhất với các nhận xét dài trải rộng trên nhiều dòng hoặc chuỗi tài liệu chiếm phần lớn thời gian bắt đầu chương trình

Kết hợp các mẹo này sẽ giúp cho việc nhận xét mã của bạn trở nên nhanh chóng, dễ dàng và dễ dàng

Khi viết mã cho chính mình

Bạn có thể làm cho cuộc sống của mình dễ dàng hơn bằng cách bình luận mã của riêng bạn đúng cách. Ngay cả khi không ai khác nhìn thấy nó, bạn sẽ thấy nó, và đó là đủ lý do để làm cho nó đúng. Rốt cuộc thì bạn cũng là một nhà phát triển, vì vậy mã của bạn cũng phải dễ hiểu đối với bạn

Một cách cực kỳ hữu ích để sử dụng nhận xét cho chính bạn là làm phác thảo cho mã của bạn. Nếu bạn không chắc chương trình của mình sẽ diễn ra như thế nào, thì bạn có thể sử dụng nhận xét như một cách để theo dõi những việc còn lại phải làm hoặc thậm chí như một cách để theo dõi luồng cấp cao của chương trình. Chẳng hạn, sử dụng nhận xét để phác thảo một chức năng trong mã giả

# This is a comment

Những bình luận này lên kế hoạch

print["This will run."]  # This won't run

Sử dụng những nhận xét như thế này có thể giúp bạn ghi nhớ mọi thứ một cách rõ ràng. Khi xem qua chương trình của mình, bạn sẽ biết những gì còn lại phải làm để có một tập lệnh đầy đủ chức năng. Sau khi “dịch” các nhận xét thành mã, hãy nhớ xóa mọi nhận xét đã trở nên dư thừa để mã của bạn luôn sắc nét và sạch sẽ

Bạn cũng có thể sử dụng nhận xét như một phần của quy trình gỡ lỗi. Nhận xét mã cũ và xem điều đó ảnh hưởng đến đầu ra của bạn như thế nào. Nếu bạn đồng ý với sự thay đổi, thì đừng để mã nhận xét trong chương trình của bạn, vì nó làm giảm khả năng đọc. Xóa nó và sử dụng kiểm soát phiên bản nếu bạn cần mang nó trở lại

Cuối cùng, sử dụng nhận xét để xác định các phần phức tạp trong mã của riêng bạn. Nếu bạn đặt một dự án xuống và quay lại với nó vài tháng hoặc vài năm sau, bạn sẽ mất rất nhiều thời gian để cố gắng làm quen lại với những gì bạn đã viết. Trong trường hợp bạn quên mã của chính mình làm gì, hãy giúp đỡ Future You và đánh dấu nó xuống để sau này dễ dàng lấy lại tốc độ hơn

Khi viết mã cho người khác

Mọi người thích lướt qua và nhảy qua lại trong văn bản và đọc mã cũng không khác. Lần duy nhất bạn có thể đọc qua từng dòng mã là khi nó không hoạt động và bạn phải tìm hiểu chuyện gì đang xảy ra

Trong hầu hết các trường hợp khác, bạn sẽ xem nhanh các biến và định nghĩa hàm để nắm được ý chính. Có nhận xét để giải thích những gì đang xảy ra bằng tiếng Anh đơn giản thực sự có thể hỗ trợ nhà phát triển ở vị trí này

Đối xử tốt với các nhà phát triển đồng nghiệp của bạn và sử dụng nhận xét để giúp họ lướt qua mã của bạn. Chú thích nội tuyến nên được sử dụng một cách tiết kiệm để xóa các đoạn mã không rõ ràng. [Tất nhiên, ưu tiên hàng đầu của bạn là làm cho mã của bạn tự đứng vững, nhưng các nhận xét nội tuyến có thể hữu ích trong vấn đề này. ]

Nếu bạn có một phương thức hoặc hàm phức tạp có tên không dễ hiểu, bạn có thể thêm một nhận xét ngắn sau dòng

# So you can't
just do this
in python

# This is a comment

Điều này có thể giúp các nhà phát triển khác đang lướt qua mã của bạn cảm nhận được chức năng của nó

Đối với bất kỳ chức năng công khai nào, bạn sẽ muốn bao gồm một chuỗi tài liệu được liên kết, cho dù nó có phức tạp hay không

# This is a comment

Chuỗi này sẽ trở thành thuộc tính

# So you can't
just do this
in python

Các hướng dẫn PEP 257 cũng có các quy ước cho các tài liệu nhiều dòng. Các chuỗi tài liệu này xuất hiện ngay trên đầu tệp và bao gồm tổng quan cấp cao về toàn bộ tập lệnh và nhiệm vụ của nó

# This is a comment

Một chuỗi tài liệu cấp mô-đun như thế này sẽ chứa mọi thông tin thích hợp hoặc cần biết để nhà phát triển đọc nó. Khi viết một cái, bạn nên liệt kê tất cả các lớp, ngoại lệ và chức năng cũng như tóm tắt một dòng cho từng loại.

Tránh xa. W. E. T. Bình luận

Nhận xét của bạn nên là D. R. Y. Từ viết tắt của câu châm ngôn lập trình “Don’t Repeat Yourself. ” Điều này có nghĩa là mã của bạn sẽ có rất ít hoặc không có dư thừa. Bạn không cần bình luận một đoạn mã có thể tự giải thích đầy đủ, như đoạn mã này

print["This will run."]  # This won't run

Chúng ta có thể thấy rõ ràng rằng

# So you can't
just do this
in python

W. E. T. nhận xét có thể là một lỗi đơn giản, đặc biệt nếu bạn đã sử dụng nhận xét để lập kế hoạch cho mã của mình trước khi viết nó. Nhưng khi bạn đã có mã chạy tốt, hãy nhớ quay lại và xóa các nhận xét không cần thiết

Tránh xa. bình luận có mùi

Nhận xét có thể là dấu hiệu của “mùi mã”, đó là bất cứ điều gì cho thấy có thể có vấn đề sâu hơn với mã của bạn. Mùi mã cố gắng che giấu các vấn đề cơ bản của chương trình và nhận xét là một cách để thử và che giấu những vấn đề đó. Nhận xét nên hỗ trợ mã của bạn, không cố gắng giải thích nó đi. Nếu mã của bạn được viết kém, sẽ không có bình luận nào sửa được

Hãy lấy ví dụ đơn giản này

print["This will run."]  # This won't run

Mã này khá ngang ngược. Có một bình luận trước mỗi dòng giải thích những gì mã làm. Tập lệnh này có thể đã được làm đơn giản hơn bằng cách gán các tên rõ ràng cho các biến, hàm và tập hợp, như vậy

print["This will run."]  # This won't run

Bằng cách sử dụng các quy ước đặt tên rõ ràng, chúng tôi có thể xóa tất cả các nhận xét không cần thiết và giảm độ dài của mã.

Nhận xét của bạn hiếm khi dài hơn mã mà họ hỗ trợ. Nếu bạn đang dành quá nhiều thời gian để giải thích những gì bạn đã làm, thì bạn cần quay lại và cấu trúc lại để làm cho mã của bạn rõ ràng và ngắn gọn hơn

Tránh xa. Nhận xét thô lỗ

Đây là điều có thể xảy ra khi làm việc trong nhóm phát triển. Khi một số người đang làm việc trên cùng một mã, những người khác sẽ tham gia và xem lại những gì bạn đã viết và thực hiện các thay đổi. Thỉnh thoảng, bạn có thể bắt gặp một người dám viết bình luận như thế này

print["This will run."]  # This won't run

Thành thật mà nói, nó chỉ là một ý tưởng tốt để không làm điều này. Sẽ không ổn nếu đó là mã của bạn bè bạn và bạn chắc chắn rằng họ sẽ không cảm thấy khó chịu vì điều đó. Bạn không bao giờ biết những gì có thể được chuyển đến sản xuất và nó sẽ trông như thế nào nếu bạn vô tình để lại nhận xét đó ở đó và một khách hàng đã phát hiện ra nó trên đường đi?