Hướng dẫn python code review best practices - các phương pháp hay nhất về đánh giá mã python

Là nhà phát triển, tất cả chúng ta đều quá quen thuộc với các đánh giá mã. Có một đôi mắt khác, hãy nhìn vào mã của chúng tôi có thể là tuyệt vời; Nó cho chúng ta thấy rất nhiều khía cạnh của mã của chúng ta, chúng ta sẽ không nhận thấy khác. Một đánh giá mã có thể là thông tin, và nó có thể mang tính giáo dục. Tôi có thể tự tin gán hầu hết những gì tôi biết về thực tiễn lập trình tốt để đánh giá mã.

Số lượng học tập mà người đánh giá lấy đi từ đánh giá mã phụ thuộc vào mức độ đánh giá được thực hiện tốt. Do đó, nó rơi vào người đánh giá để thực hiện số lượng đánh giá của họ bằng cách đóng gói nhiều bài học nhất vào đánh giá càng tốt.

Đây là một hướng dẫn về một số khía cạnh quan trọng của mã bạn nên kiểm tra trong các đánh giá của mình, những kỳ vọng bạn nên có từ các kiểm tra đó và một số ý tưởng về cách thức công cụ (như linter, định dạng và bộ kiểm tra) có thể giúp hợp lý hóa quy trình .

Danh sách kiểm tra xem xét mã

Chúng tôi đã xây dựng hướng dẫn này dưới dạng một danh sách kiểm tra. Nó liệt kê một tập hợp các câu hỏi mà bạn cần hỏi về mã. Nếu câu trả lời cho bất kỳ ai trong số họ không phải là 'có', bạn nên để lại nhận xét về PR.

Xin lưu ý rằng danh sách này chỉ có nghĩa là phục vụ như một hướng dẫn. Cơ sở mã của bạn, như mọi cơ sở mã, có bộ nhu cầu cụ thể của riêng mình, vì vậy hãy thoải mái xây dựng hướng dẫn này và ghi đè các phần của nó không phù hợp với các trường hợp sử dụng của bạn.

Nghi thức

Điều đầu tiên và quan trọng nhất cần kiểm tra trong quá trình đánh giá là mức độ chặt chẽ của PR tuân thủ các nghi thức cơ bản. PR tốt bao gồm các thay đổi có kích thước cắn và giải quyết một vấn đề được xác định rõ ràng. Chúng nên được tập trung và có mục đích hẹp để có ít xung đột hợp nhất nhất có thể. Nói một cách đơn giản, một PR tốt tạo điều kiện được xem xét.

Đối với các thay đổi súp điện quy mô lớn, hãy tạo một nhánh mục tiêu riêng biệt và sau đó tạo các PR gia tăng nhỏ cho mục tiêu đó, cuối cùng hợp nhất mục tiêu với nhánh chính. Làm cho một PR hài hước làm cho việc xem xét lại khó khăn hơn, và nếu nó trở nên cũ kỹ, nhiều xung đột hợp nhất có thể bật lên.

Khi xem xét PRS từ các nhà phát triển mới, tôi cũng làm cho nó trở thành một điểm để đảm bảo các thông điệp cam kết của họ được viết tốt.

Checklist:

• Là nguyên tử PR?
• PR có tuân theo nguyên tắc quan tâm duy nhất không?
• Các thông điệp cam kết có được viết tốt không?

Ideas:

Thực thi một định dạng tin nhắn cam kết trong nhóm. Ví dụ: bạn có thể thử gitmoji trong đó bạn sử dụng biểu tượng cảm xúc trong các tin nhắn cam kết. Ví dụ, lỗi nên bắt đầu với [FIX] hoặc 🐛 Emoji và các tính năng mới nên bắt đầu với [FEAT] hoặc ✨ Emoji. Điều này làm cho ý định của cam kết rất rõ ràng.

Chức năng và cú pháp

Điều tiếp theo cần kiểm tra là liệu PR có hiệu quả trong đó nó hoạt động hay không. Mã thay đổi bởi PR nên hoạt động như mong đợi. Một sửa lỗi sẽ giải quyết lỗi mà nó được cho là sửa chữa. Một tính năng sẽ cung cấp các chức năng bổ sung được yêu cầu mà không phá vỡ thứ khác.

Một điều quan trọng cần ghi nhớ là bất kỳ tính năng mới nào được thêm bởi PR đều hợp lý. Một cách đơn giản để đảm bảo điều này là chỉ chấp nhận các PR được liên kết với một vấn đề đã được xử lý. Thực hành này giảm thiểu tính năng-creep.

Checklist:

• PR có hoạt động không?
• Tính năng mới có thêm giá trị hay nó là dấu hiệu của tính năng creep?
• PR có thêm trường hợp kiểm tra cho mã sửa đổi không?

Ideas:

Có các bài kiểm tra toàn diện trong mã giúp dễ dàng kiểm tra liệu chức năng mới có hoạt động và PRS khó khăn hơn để phá vỡ các công cụ hiện có không. Phần của mã được bảo hiểm không bao giờ nên đi xuống trong PR. Bất kỳ mã mới sẽ đi kèm với phạm vi bảo hiểm hoàn chỉnh trong các bài kiểm tra đơn vị/chức năng. Python đi kèm với một khung thử nghiệm đơn vị mạnh mẽ được tích hợp trong chính ngôn ngữ. Bạn nên sử dụng nó trong cơ sở mã của mình.

Thiết kế

Khi chúng tôi đã thiết lập rằng mã hoạt động, bước tiếp theo là kiểm tra xem nó tích hợp tốt như thế nào với cơ sở mã hiện có. Một điều quan trọng để kiểm tra về vấn đề này là trùng lặp. Thông thường, mã được thêm vào repo cung cấp chức năng có thể đã là một phần của mã ở một vị trí khác hoặc một cái gì đó được cung cấp bởi các khung hoặc gói PIP đang sử dụng. Kiến thức này là một cái gì đó mà người ta chỉ có thể đạt được bằng kinh nghiệm. Là một tiền bối, nó trở thành nhiệm vụ của bạn để chỉ ra sự trùng lặp như vậy cho các nhà phát triển mới đóng góp cho repo của bạn.

Chú ý đến các mô hình cũng là điều cần thiết. Nhiều dự án có các mô hình thiết kế được điều chỉnh sẵn như microservice, mono repo hoặc cloud-nativity. Bất kỳ mã đến phải phù hợp với các mô hình này.

Checklist:

• Mã có được lên kế hoạch và thiết kế đúng không?
• Mã có hoạt động tốt với mã hiện có và không tăng sự trùng lặp?
• Mã có được tổ chức tốt về vị trí của các thành phần không?

Mẫu và thành ngữ

Python là một ngôn ngữ rất trưởng thành. Nó được thúc đẩy dựa trên một số triết lý nhất định, được mô tả là Thiền của Python. Những triết lý đó đã sinh ra nhiều công ước và thành ngữ mà mã mới dự kiến ​​sẽ tuân theo.

Sự khác biệt giữa mã thành ngữ và không ifiomatic là rất tinh tế, và trong hầu hết các trường hợp, chỉ có thể được đánh giá bằng trực giác. Như với tất cả những điều được mài giũa bởi kinh nghiệm, trực giác phải được chuyển từ những người có kinh nghiệm, như chính bạn, sang những người mới như những người đánh giá của bạn.

Checklist:

• Mã có giữ được với các thành ngữ và mẫu mã của ngôn ngữ không?
• Mã có sử dụng các tính năng ngôn ngữ và thư viện tiêu chuẩn không?

Ideas:

Hầu hết các lin, phổ biến là pylint, có thể giúp bạn xác định độ lệch so với các hướng dẫn kiểu và, trong hầu hết các trường hợp, thậm chí tự động sửa chúng. Linters hoạt động cực kỳ nhanh và có thể điều chỉnh mã trong thời gian thực, làm cho chúng trở thành một bổ sung có giá trị cho công cụ của bạn.

Khả năng đọc

Python được coi là một ngôn ngữ rất dễ đọc. Sự đơn giản của cú pháp Python và giảm việc sử dụng dấu câu đóng góp rất nhiều vào khả năng đọc của nó. Nó chỉ có ý nghĩa đối với mã được viết bằng ngôn ngữ cũng có thể đọc được.

Checklist:

• Mã có rõ ràng và súc tích không?
• Nó có tuân thủ PEP-8 không?
• Có phải tất cả các quy ước ngôn ngữ và dự án đều được theo sau?
• Các định danh có được đưa ra những cái tên tuân thủ hướng dẫn có ý nghĩa và phong cách không?

Ideas:

Một định dạng mã tốt như màu đen có thể giúp rất nhiều trong việc định dạng mã cho tính nhất quán và khả năng đọc. Black cũng cung cấp tùy chỉnh tối thiểu, điều này là tốt vì nó loại bỏ tất cả các hình thức bikeshing.

Trước đây chúng tôi đã nói về việc tích hợp màu đen vào đường ống CI của bạn có thể làm việc kỳ diệu trong quá trình xem xét mã.

Tài liệu và khả năng bảo trì

Điều tiếp theo cần kiểm tra là khả năng duy trì của mã. Bất kỳ mã nào được thêm hoặc thay đổi bởi PR nên được viết để tạo điều kiện cho ai đó không phải là tác giả ban đầu để duy trì nó.

Tốt nhất là nó nên tự ghi chép, có nghĩa là được viết theo cách mà bất kỳ ai đọc mã đều có thể hiểu được nó làm gì. Đây là một trong những đặc điểm nổi bật của mã Python tốt. Nếu mã phải phức tạp theo thiết kế, nó nên được ghi lại. Trong một thế giới lý tưởng, tất cả các lớp học và chức năng sẽ có các tài liệu Python, hoàn chỉnh với các ví dụ.

Checklist:

• Mã tự ghi chép hay tài liệu tốt?
• Là mã không bị che khuất và sự phức tạp không cần thiết?
• Là dòng điều khiển và mối quan hệ thành phần rõ ràng để hiểu?

Ideas:

Sphinx là một trình tạo tài liệu xuất khẩu tài liệu đẹp từ các tài liệu Python. Tài liệu được xuất sau đó có thể được tải lên ReadThedocs, một công cụ lưu trữ tài liệu phổ biến. Sphinx là một trong những lý do chính khiến tôi hoàn toàn thích viết tài liệu.

Bảo vệ

Đảm bảo rằng ứng dụng vẫn an toàn là rất quan trọng. Điều tiếp theo cần kiểm tra là nếu PR duy trì hoặc cải thiện bảo mật của dự án. Bạn cần đảm bảo rằng những thay đổi không làm tăng diện tích bề mặt tấn công hoặc phơi bày các lỗ hổng. Nếu PR thêm các phụ thuộc mới, chúng có khả năng không an toàn, trong trường hợp đó bạn có thể cần kiểm tra phiên bản để khai thác đã biết và cập nhật các phụ thuộc, nếu cần thiết.

Checklist:

• Là mã không có lỗi thực hiện có thể được khai thác?
• Có phải tất cả các phụ thuộc mới đã được kiểm toán cho các lỗ hổng?

Ideas:

Một trong những nhà phân tích bảo mật nổi tiếng cho Python là Bandit. Ngoài ra, nếu bạn sử dụng GitHub cho mã lưu trữ, bạn hoàn toàn nên đọc hướng dẫn này về việc thiết lập phát hiện lỗ hổng và phụ thuộc vào cơ sở mã của bạn.

Khi bạn thiết lập phát hiện lỗ hổng trên GitHub, bạn sẽ nhận được thông báo như thế này ...

... với chi tiết về lỗ hổng và PR trong kho lưu trữ mà bạn có thể hợp nhất để vá chúng.

Gần đây chúng tôi cũng đã nói về những cạm bẫy an ninh chung trong phát triển Python và cách bạn có thể đảm bảo các dự án của mình chống lại chúng.

Hiệu suất, độ tin cậy và khả năng mở rộng

Những điều cuối cùng cần kiểm tra là hiệu suất và độ tin cậy của mã ở quy mô. Mặc dù đây chắc chắn là các số liệu quan trọng, tôi đặt chúng ở cuối danh sách kiểm tra vì tôi tin rằng mã được lên kế hoạch tốt, được thiết kế tốt và được viết tốt thường cũng hoạt động tốt.

Checklist:

• Mã có được tối ưu hóa về mặt phức tạp về thời gian và không gian không?
• Nó có quy mô theo nhu cầu không?
• Nó có thiết bị như báo cáo cho các số liệu và cảnh báo cho các thất bại?

Ideas:

Một cách tuyệt vời để có thêm một số độ tin cậy cho Python là sử dụng kiểm tra kiểu và loại tĩnh có thể cung cấp gợi ý về các lỗi có thể xảy ra trước thời gian chạy. Hỗ trợ bản địa mới của Python cho các loại phụ đề chủ yếu được lấy cảm hứng từ cú pháp MyPy, có thể được áp dụng tăng dần trong các dự án hiện có.

DEEPSOURCE

DeepSource là một công cụ đánh giá mã tự động, quản lý quy trình quét mã từ đầu đến cuối và tự động thực hiện các yêu cầu kéo với các bản sửa lỗi bất cứ khi nào các cam kết mới được đẩy hoặc yêu cầu kéo mới.

Thiết lập DeepSource cho Python & NBSP; là một quy trình nhanh chóng, dễ dàng, không ồn ào. Chỉ cần thêm một tệp .deepsource.toml vào gốc của repo và ngay lập tức DeepSource sẽ chọn nó để quét. Việc quét sẽ tìm thấy phạm vi để cải thiện trên cơ sở mã của bạn, thực hiện các cải tiến đó và mở các yêu cầu kéo cho các thay đổi mà nó tìm thấy. Tôi đã bị thổi bay bởi sự đơn giản của thiết lập và hiệu quả của động cơ mã tự chế tạo của họ.

Trivia: Bạn có biết rằng DeepSource nắm giữ sự khác biệt của việc nằm trong danh sách các công cụ phân tích mã nguồn cho Python không?Trivia: Did you know that DeepSource holds the distinction of being on OWASP’s curated list of source code analysis tools for Python?

Đánh giá mã lý tưởng

Quay trở lại quan điểm của tôi về các đánh giá mã là giáo dục và thông tin, tôi cũng muốn thêm rằng các đánh giá mã là tốn nhiều thời gian và tốn nhiều tài nguyên. Trong khi mỗi đánh giá cần có thời gian, thì những người chuyên sâu và toàn diện sẽ tiêu thụ nhiều hơn nữa.

Vì vậy, mỗi đánh giá phải có hiệu quả nhất có thể. Đây là nơi mà tất cả các nỗ lực công cụ và tự động hóa nên được định hướng. Bằng cách tự động hóa bất cứ điều gì có thể được tự động hóa, nói chung là các phần trần tục của đánh giá, chẳng hạn như kiểu mã và định dạng, chúng ta có thể cho phép các nhà phát triển tập trung vào các công cụ quan trọng như kiến ​​trúc, thiết kế và khả năng mở rộng.

Tôi sẽ để lại cho bạn một suy nghĩ sâu sắc mà người cố vấn của tôi chia sẻ với tôi.

Một đánh giá mã tốt không chỉ cải thiện mã mà cả lập trình viên nữa.

Làm thế nào để bạn viết một đánh giá mã tốt?

Các linter mã Python tốt nhất là gì?

Danh sách kiểm tra đánh giá mã là gì?

Làm thế nào tôi có thể cải thiện kỹ năng xem xét mã của mình?