Trả về chuỗi tài liệu Python
Ghi lại mã của bạn là một kỹ năng quan trọng đối với bất kỳ nhà khoa học dữ liệu hoặc kỹ sư phần mềm nào. Tìm hiểu làm thế nào để làm điều đó bằng cách sử dụng docstringsTại sao tài liệu trong Python lại quan trọng?Điều này cho chúng ta biết rằng "Khả năng đọc được tính" và "Rõ ràng tốt hơn ẩn. " Đây là những đặc điểm cần thiết của Python. Khi chúng tôi viết mã, chúng tôi làm điều đó cho người dùng cuối, nhà phát triển và chính chúng tôi Show
Hãy nhớ rằng chúng ta cũng là người dùng cuối khi đọc tài liệu 6 hoặc tài liệu 7. Hai gói này có tài liệu tuyệt vời và người dùng thường không gặp khó khăn gì khi sử dụng chúng vì chúng chứa rất nhiều ví dụ và hướng dẫn. Họ cũng có tài liệu tích hợp mà chúng tôi có thể truy cập trực tiếp vào IDE ưa thích của bạnBây giờ hãy tưởng tượng sử dụng các gói này mà không có bất kỳ tài liệu tham khảo nào. Chúng tôi sẽ cần tìm hiểu mã của họ để hiểu nó làm gì và cách chúng tôi có thể sử dụng nó. Có một số gói hoàn toàn không có tài liệu hướng dẫn và thường mất nhiều thời gian hơn để hiểu những gì bên trong chúng và cách chúng ta có thể sử dụng chúng. Khối lượng công việc này tăng gấp đôi hoặc gấp ba nếu gói lớn, với các chức năng trải rộng trên nhiều tệp Bây giờ rõ ràng hơn tại sao tài liệu tốt lại được tính Tiếp theo, các nhà phát triển khác có thể muốn đóng góp cho các dự án của chúng tôi. Họ có thể làm điều đó nhanh hơn và hiệu quả hơn nhiều nếu mã của chúng tôi được ghi chép đầy đủ. Bạn có muốn đóng góp cho một dự án trong thời gian rảnh nếu bạn phải dành hàng giờ để tìm hiểu những phần khác nhau của nó làm gì không? Cuối cùng, ngay cả khi đó chỉ là dự án riêng của chúng tôi hoặc một tập lệnh nhỏ, chúng tôi vẫn cần tài liệu. Chúng tôi không bao giờ biết khi nào chúng tôi sẽ quay lại một trong những dự án cũ của mình để sửa đổi hoặc cải thiện nó. Thật thú vị và dễ làm việc với nó nếu nó cho chúng ta biết rõ ràng nó dùng để làm gì và các chức năng, dòng mã và mô-đun của nó làm gì. Chúng ta có xu hướng nhanh chóng quên đi những gì mình đang nghĩ trong quá trình viết mã, vì vậy, dành thời gian giải thích lý do tại sao chúng ta đang làm điều gì đó luôn tiết kiệm nhiều thời gian hơn khi quay lại mã (ngay cả khi nó mới được viết một ngày trước). Vì vậy, hãy đầu tư một chút thời gian vào tài liệu và nó sẽ đền đáp cho bạn sau này Ví dụ về tài liệu PythonHãy xem qua một số ví dụ về chuỗi tài liệu trong Python. Ví dụ: một hàm tầm thường bên dưới nhận hai biến và trả về tổng của chúng (theo mặc định) hoặc hiệu giữa chúng
Chức năng này khá đơn giản, nhưng để chứng minh sức mạnh của chuỗi tài liệu Python, hãy viết một số tài liệu
Chuỗi tài liệu Python của hàm này được đặt giữa ba dấu ngoặc kép từ cả hai phía. Như bạn có thể thấy, chuỗi này giải thích chức năng này làm gì và cho biết cách chúng ta có thể thay đổi chức năng của nó — và điều gì xảy ra nếu nó không hỗ trợ hành động mà chúng ta muốn nó thực hiện. Đó là một ví dụ đơn giản và bạn có thể lập luận rằng chức năng này quá rõ ràng để yêu cầu bất kỳ lời giải thích nào, nhưng một khi các chức năng trở nên phức tạp và số lượng của chúng tăng lên, bạn sẽ cần ít nhất một số tài liệu để tránh bị lạc trong mã của chính mình Điều gì đang xảy ra dưới mui xe? . Tất cả các gói tài liệu tốt đều có chuỗi tài liệu cho (gần như) tất cả các chức năng của chúng. Ví dụ: hãy xem DataFrame trong pandas
Bây giờ, nếu chúng ta xem mã nguồn của 6, chúng ta sẽ thấy rằng 1 cho chúng ta thấy chuỗi tài liệu của lớp 2 (tìm kiếm 3)Về mặt kỹ thuật, chuỗi tài liệu được gán cho một thuộc tính được tạo tự động của đối tượng này có tên là 4. Chúng ta cũng có thể in thuộc tính này ra và thấy rằng nó hoàn toàn giống như trước đây 4 5Sự khác biệt giữa Tài liệu và Nhận xét mãSau khi chúng tôi đã thấy các chuỗi tài liệu trông như thế nào, đã đến lúc tìm hiểu lý do và cách chúng khác với các nhận xét mã thông thường. Ý tưởng chính là chúng (thường) phục vụ các mục đích khác nhau Các tài liệu giải thích chức năng/lớp cần thiết để làm gì (i. e. , mô tả, đối số và đầu ra của nó — và bất kỳ thông tin hữu ích nào khác) trong khi nhận xét giải thích chức năng của các chuỗi mã cụ thể. Nói cách khác, nhận xét mã dành cho những người muốn sửa đổi mã và chuỗi tài liệu dành cho những người muốn sử dụng mã Ngoài ra, nhận xét mã có thể hữu ích khi lập kế hoạch mã (ví dụ: bằng cách triển khai mã giả hoặc để lại nhận xét tạm thời về ý tưởng hoặc suy nghĩ của bạn không dành cho người dùng cuối) Định dạng chuỗi tài liệuHãy xem xét các loại docstrings khác nhau. Đầu tiên, bạn nên duyệt qua các trang PEP của Python. Chúng ta có thể tìm thấy PEP 257, tóm tắt các tài liệu Python. Tôi thực sự khuyên bạn nên đọc tất cả mặc dù bạn có thể không hiểu tất cả. Các điểm thiết yếu như sau
Lưu ý rằng đây chỉ là những khuyến nghị và không phải là quy tắc nghiêm ngặt. Ví dụ: tôi nghi ngờ rằng chúng ta sẽ cần bổ sung thêm thông tin về các đối số hoặc đầu ra cho hàm 9 vì bản tóm tắt đã đủ mô tảCó bốn loại tài liệu chính, tất cả đều tuân theo các khuyến nghị trên
Bạn có thể xem tất cả chúng và quyết định cái nào bạn thích nhất. Các chuỗi tài liệu NumPy/SciPy và Google sẽ xuất hiện thường xuyên hơn mặc dù reStructuredText là kiểu tài liệu chính thức của Python Hãy xem xét một tập dữ liệu trong thế giới thực và viết một hàm để áp dụng cho một trong các cột của nó Bộ dữ liệu này chứa các trò chơi điện tử hàng đầu trên Metacritic trong giai đoạn 1995-2021 7____18Ví dụ: chúng tôi có thể quan tâm đến việc tạo một cột tính toán số ngày trước một trò chơi đã được phát hành. Với mục đích này, chúng tôi cũng sẽ sử dụng gói 6 (hướng dẫn một, hướng dẫn hai)Đầu tiên, hãy viết chức năng này và kiểm tra nó 0 0Chức năng này hoạt động như dự định, nhưng tốt hơn là bổ sung cho nó bằng các chuỗi tài liệu. Trước hết, hãy sử dụng định dạng SciPy/NumPy 1Ở trên trong phần 7, tôi không lặp lại (hầu hết) những gì đã có trong phần tóm tắtTiếp theo, một ví dụ về tài liệu của Google 2Một ví dụ về cấu trúc lại văn bản 3Cuối cùng, một ví dụ Epytext 4Hầu hết các chuỗi tài liệu chức năng phải có ít nhất một bản tóm tắt về chức năng, mô tả đầu vào và đầu ra của chúng. Hơn nữa, nếu chúng phức tạp hơn, chúng có thể bao gồm các ví dụ, ghi chú, ngoại lệ, v.v. Cuối cùng, tôi không nói nhiều về các lớp vì chúng không thường xuyên xuất hiện trong khoa học dữ liệu, nhưng ngoài các phương thức (chức năng) của chúng bao gồm những gì, chúng cũng nên có những điều sau
Tài liệu kịch bảnCác tài liệu Python cũng mô tả chức năng và nguyên tắc sử dụng của các tập lệnh nhỏ, có thể phù hợp để tự động hóa một số tác vụ hàng ngày của chúng ta. Ví dụ: tôi thường xuyên cần đổi kroner Đan Mạch sang euro. Tôi có thể nhập một truy vấn trên Google mỗi lần hoặc tôi có thể tải xuống một ứng dụng có thể thực hiện điều đó cho tôi, nhưng tất cả dường như quá phức tạp và dư thừa. Tôi biết rằng một euro là khoảng 7. 45 krone Đan Mạch và vì tôi hầu như luôn làm việc trong thiết bị đầu cuối Linux, nên tôi quyết định viết một chương trình CLI nhỏ để chuyển đổi loại tiền này sang loại tiền khác 5Tập lệnh phải được ghi lại đầy đủ để cho phép người dùng áp dụng nó. Ở đầu tệp, một chuỗi tài liệu sẽ mô tả mục đích chính của tập lệnh, hướng dẫn ngắn gọn và các hàm hoặc lớp chứa trong đó. Ngoài ra, nếu bất kỳ gói của bên thứ ba nào được sử dụng, gói đó phải được nêu trong tài liệu để người dùng cài đặt gói đó trước khi sử dụng tập lệnh Nếu bạn sử dụng mô-đun 8 để tạo các ứng dụng CLI, thì mỗi đối số của nó phải được mô tả trong menu 1 để người dùng cuối có thể chọn tùy chọn 0 và xác định đầu vào. Hơn nữa, tham số 1 phải được điền vào trong đối tượng 2Cuối cùng, tất cả các chức năng phải được ghi lại đúng cách như đã mô tả trước đây. Ở đây, tôi đã bỏ qua các bộ mô tả "Đối số" và "Trả về" bởi vì, theo quan điểm của tôi, chúng không cần thiết Ngoài ra, hãy lưu ý cách tôi sử dụng nhận xét mã và cách chúng khác với chuỗi tài liệu. Nếu bạn có một kịch bản bạn đã viết, hãy thêm vào đó một số tài liệu để thực hành Lời khuyên chung về cách viết tài liệu và tài liệu PythonKhá rõ ràng tại sao tài liệu lại quan trọng và tại sao chuỗi tài liệu là một phần thiết yếu của tài liệu Python. Để kết thúc, hãy để tôi cung cấp cho bạn một số lời khuyên chung về tài liệu và chuỗi tài liệu Python
Tóm lượcĐây là những gì chúng ta đã học được trong hướng dẫn này
Tôi hy vọng rằng bạn đã học được một cái gì đó mới ngày hôm nay. Vui lòng kết nối với tôi trên LinkedIn hoặc GitHub. Mã hóa vui vẻ Khoa học dữ liệu hướng dẫn Python Giới thiệu về tác giả Artur SannikovTôi là sinh viên Sinh học phân tử tại Đại học Padua, Ý quan tâm đến tin sinh học và phân tích dữ liệu Làm cách nào để tạo chuỗi tài liệu trong Python?Khai báo Docstrings. Các chuỗi tài liệu được khai báo bằng cách sử dụng ”'ba dấu ngoặc đơn”' hoặc “””ba dấu ngoặc kép””” ngay bên dưới phần khai báo lớp, phương thức hoặc hàm . Tất cả các chức năng nên có một chuỗi tài liệu.
Bạn có thể định dạng một chuỗi Python không?Chuỗi tài liệu Python có thể được viết theo một số định dạng như các bài đăng khác đã trình bày. Tuy nhiên, định dạng chuỗi tài liệu Sphinx mặc định không được đề cập và dựa trên reStructuredText (reST). Bạn có thể nhận được một số thông tin về các định dạng chính trong phần hướng dẫn đó. Có các định dạng được sử dụng chính cho docstrings.
Chuỗi tài liệu đi đâu?Chuỗi tài liệu là một chuỗi ký tự xuất hiện dưới dạng câu lệnh đầu tiên trong định nghĩa mô-đun, hàm, lớp hoặc phương thức . Một chuỗi tài liệu như vậy trở thành thuộc tính đặc biệt __doc__ của đối tượng đó.
__ doc __ nghĩa là gì trong Python?Thuộc tính __doc__
. ) cung cấp (nếu lập trình viên điền vào) một tài liệu ngắn mô tả các tính năng của nó . Bạn có thể truy cập nó bằng các lệnh như print myobject. |