Chuỗi tài liệu NumPy

Vì chúng ta đã biết cách viết các nhận xét nhiều dòng, chúng ta có thể sử dụng dấu ngoặc kép ba đơn hoặc ba dấu ngoặc kép. Chúng tôi sử dụng một chuỗi tài liệu khi chúng tôi muốn mô tả các chức năng của mình để chúng tôi có thể lấy tài liệu khi cần. Một số IDE cung cấp cho bạn tài liệu bằng cách di chuột qua tên và một số đánh dấu các từ khóa nhất định. Nhưng thực tế là docstrings trong NumPy linh hoạt hơn các ngôn ngữ khác. Docstring là một ký tự chuỗi xuất hiện ở đầu định nghĩa hàm. Chúng ta phải cung cấp các giá trị cụ thể trong khi sử dụng docstrings trong các trường hợp hàm, lớp, v.v.

Khi sử dụng docstrings với các hàm, chúng ta phải truyền các đối số. Khi sử dụng chúng với các lớp, chúng ta chuyển các thuộc tính và phương thức. Trong trường hợp của Mô-đun, chúng ta phải cung cấp danh sách các lớp và chức năng. Trong trường hợp của gói, chúng tôi chuyển danh sách các mô-đun có chức năng. Vì vậy, về cơ bản, mục đích của docstring, như tên giải thích, là nó giúp tạo tài liệu cho mã của chúng ta. Chúng tôi làm tài liệu để nếu ai đó sử dụng mã của chúng tôi trong tương lai, họ sẽ có thể hiểu mã của chúng tôi và logic đằng sau mã của chúng tôi với sự trợ giúp của docstring. Các hàm dựng sẵn cũng có docstrings trong đó; chúng ta có thể sử dụng hàm help () để xem chuỗi tài liệu của các hàm tích hợp sẵn.

Có một số khác biệt giữa nhận xét và docstrings. Các bình luận bị thông dịch viên bỏ qua nhưng docstrings không bị thông dịch viên bỏ qua. Bộ nhớ được cấp cho docstrings. Một nhận xét là một mô tả về mã nhưng mặt khác, docstrings cho chúng ta biết mục đích của mã.

Cú pháp:

Cú pháp để viết docstrings trong NumPy là:

Xin lưu ý rằng docstring không phải là một hàm hoặc phương thức, vì vậy nó không có cú pháp thích hợp. Điều duy nhất cần lưu ý ở đây là chúng ta bắt đầu chuỗi doc với ba dấu nháy đơn hoặc ba dấu nháy kép. Chúng tôi viết mô tả của chúng tôi về mã và kết thúc nó một lần nữa bằng ba dấu ngoặc kép đơn hoặc ba dấu ngoặc kép ở cuối. Không có điều gì bắt buộc phải viết cho docstrings. Bạn chỉ cần đặt ba dấu ngoặc kép đơn hoặc kép trước và sau mô tả chuỗi của bạn.

Ví dụ 1:

Để hiểu docstrings một cách tốt hơn, hãy làm một ví dụ. Trong ví dụ này, sau khi bao gồm thư viện NumPy, chúng ta chỉ cần khai báo biến “a” và một biến khác “b”. Sau đó, chúng tôi tạo chuỗi tài liệu của mình có nội dung “Hãy để chúng tôi thêm các biến“ a ”và“ b ””. Trong trường hợp của chúng tôi, đây là một ví dụ dễ dàng nhưng nếu mã của chúng tôi phức tạp, điều này sẽ giúp lập trình viên rất nhiều trong việc hiểu mã. Sau đó, chúng tôi tổng hợp các biến “a” và “b” và lưu trữ kết quả đầu ra của chúng trong một biến khác là “c”. Cuối cùng, chúng tôi in ra giá trị của biến “c”. Bây giờ, chúng tôi thực thi mã của chúng tôi.

Đây là đầu ra của chúng tôi từ đoạn mã đã cho. Chúng tôi có thể thấy rằng hệ thống đã không đưa ra bất kỳ lỗi nào về cú pháp không chính xác hoặc bất kỳ điều gì đối với dòng 7 trong mã của chúng tôi. Ngoài ra, hệ thống chưa in chuỗi tài liệu của chúng tôi. Thay vào đó, nó chỉ in kết quả đầu ra của biến “c” mà chúng tôi yêu cầu hệ thống của chúng tôi in. Điều này cho thấy cách hoạt động của docstrings. Lần tới, khi một lập trình viên mới cố gắng làm việc trên mã của chúng tôi, anh ta sẽ hiểu chúng tôi đang làm gì với sự trợ giúp của chuỗi docstring của chúng tôi. Nhưng nó sẽ không được in dưới dạng đầu ra nên người dùng mã sẽ không bị quấy rầy bởi nó.

Ví dụ 2:

Bây giờ, chúng tôi thực hiện một ví dụ phức tạp để hiểu docstring đang hoạt động. Đầu tiên, chúng tôi đưa vào thư viện NumPy và sau đó viết một chuỗi doc, trong đó chúng tôi giải thích dòng mã tiếp theo, nơi chúng tôi giải thích việc khởi tạo mảng. Chúng tôi cũng thêm docstrings vào phần khác của mã. Bây giờ, nếu chúng tôi chia sẻ mã này với bất kỳ nhà phát triển Python mới nào mà không thêm docstrings, bằng cách nào đó sẽ rất khó để anh ta biết hoạt động và mục đích của mã này. Anh ấy phải tìm kiếm trước về các chức năng mà chúng tôi đã sử dụng. Nhưng nếu chúng ta thêm chuỗi tài liệu vào mã của mình, các nhà phát triển khác sẽ dễ dàng hiểu mã mà không cần nghiên cứu thêm về các chức năng. Chúng tôi không bị giới hạn trong việc thêm nhận xét vào một số giới hạn; nhận xét có thể gồm một hoặc nhiều dòng. Nó cũng có thể được thêm nhiều lần trong một mã. Sau đó, nhập NumPy dưới dạng np.

Như được hiển thị trong đoạn mã sau, docstrings không được hiển thị trong đầu ra, có nghĩa là nó không ảnh hưởng đến đầu ra hoặc quá trình biên dịch mã. Các chuỗi tài liệu bị bỏ qua trong quá trình biên dịch.

Sự kết luận

Trong hướng dẫn này, chúng ta đã tìm hiểu về docstrings trong NumPy. Chúng tôi đã so sánh docstrings với các nhận xét và giải thích sự khác biệt giữa cả hai. Chúng tôi đã học cú pháp của docstrings và cách viết docstrings trong mã của chúng tôi. Hơn nữa, chúng tôi cũng cố gắng giải thích các docstrings trong NumPy là gì và cách chúng hoạt động với sự trợ giúp của các ví dụ. Cuối cùng, chúng tôi nhận xét rằng chúng rất cần thiết cho các lập trình viên. Chúng tôi sẽ không nhắc lại tầm quan trọng của docstrings trong NumPy. Chúng tôi sẽ chỉ nói rằng bạn nên sử dụng docstrings trong mã của mình. Trong NumPy, kiểu viết docstrings là kiểu phổ biến nhất. Nó được sử dụng rộng rãi trong cộng đồng lập trình để cho nhau biết về hoạt động và chức năng của mã của họ. Hướng dẫn này sẽ giúp bạn bắt đầu với docstrings NumPy. Chúng tôi đã cố gắng bao gồm hầu hết những gì bạn sẽ cần bằng cách sử dụng docstrings trong NumPy.