Cách ghi chép mã Python

Nếu bạn mới bắt đầu với Python và muốn học thêm, hãy tham gia khóa Intermediate Python của DataCamp.

Tầm quan trọng của việc ghi chép cho dự án

Tài liệu là phần thiết yếu của bất kỳ dự án nào bạn thực hiện, bất kể ngôn ngữ lập trình. Một dự án có ứng dụng với nhiều API đang hoạt động và được nhiều người dùng sử dụng nhưng thiếu tài liệu sẽ bị coi là chưa hoàn chỉnh. Hãy thử đặt mình vào vị trí lập trình viên: bạn sẽ thấy thế nào nếu muốn tái tạo một dự án hoặc dùng một phần của dự án mà không có tài liệu? Chắc chắn bạn sẽ gặp khó khăn khi tích hợp vào kiến trúc của mình.

Tài liệu tốt sẽ giúp dự án của bạn thành công hơn vì khi chia sẻ dự án hay phần mềm với cộng đồng, bạn muốn mọi người sử dụng nó; đặc biệt với dự án mã nguồn mở, mục tiêu này còn rõ ràng hơn. Bạn cũng muốn cộng đồng đóng góp để dự án ngày càng tốt hơn.

Tác giả nổi tiếng của ngôn ngữ lập trình Python có câu nói rằng Code is more often read than written. Câu nói này nhấn mạnh tầm quan trọng của tài liệu đối với mã nguồn hay dự án khi được người khác triển khai.

Hãy tưởng tượng bạn là nhân viên của công ty XYZ, đang trong thời gian bàn giao, và quản lý muốn bạn chuyển giao dự án cho đồng nghiệp. Bạn có thể thực hiện KT (knowledge transfer), nhưng nếu đồng nghiệp không chạy thành công một đoạn mã trong dự án thì sao? Có nhiều lý do khiến mã không chạy, ví dụ các binary mà mã của bạn dựa vào không khớp với binary của hệ điều hành hiện tại.

Tài liệu dự án chính xác là gì?

Tài liệu gồm nhiều thành phần. Nó cần được cấu trúc tốt xoay quanh các thành phần đó và tuân thủ để được coi là tài liệu đúng chuẩn.

Ở mức khái quát, các thành phần gồm:

• Đảm bảo codebase của dự án được chú thích rõ ràng.

• Tuân theo tiêu chuẩn mã hóa PEP-8 của Python.

• Các hướng dẫn cụ thể về cách xây dựng dự án, đặc biệt khi là dự án mã nguồn mở phục vụ mục đích học tập.

• Hướng dẫn cài đặt các gói, mô-đun cần thiết để xây dựng phần mềm; bảng thông số kỹ thuật nếu dự án có phần cứng. Ví dụ, cách cài anaconda, TensorFlow, Keras, v.v.

• Nhiều thảo luận về tiến độ dự án tại từng thời điểm, có thể dẫn đến việc triển khai phần mềm thành công.

• Tài liệu tham khảo cung cấp mô tả kỹ thuật về ngăn xếp công nghệ được dùng trong giai đoạn phát triển.

• Thiết kế kiến trúc của dự án hoặc giải pháp phần mềm.

Những điểm trên chỉ là một số thành phần có thể có trong một tài liệu được cấu trúc tốt và trông hoàn chỉnh. Quan trọng là giữ các thành phần này tách bạch, giúp việc bảo trì tài liệu sau này dễ dàng hơn.

Một ví dụ về tài liệu toàn diện có hầu hết các thành phần đã nêu sẽ tương tự như minh họa dưới đây:

Nhiều người thường nhầm lẫn giữa commenting & documenting và coi chúng giống nhau. Comment dùng để mô tả mã cho người dùng, người bảo trì và chính bạn trong tương lai. Comment chỉ hoạt động ở cấp độ mã và có thể xem là một tập con của tài liệu. Comment giúp người đọc:

• hiểu mã của bạn,
• khiến nó tự giải thích, và
• hiểu mục đích và thiết kế.

Cần nhớ rằng vì Python tuân theo tiêu chuẩn PEP-8, ngay cả comment cũng phải tuân thủ. Tài liệu chính thức của Python nêu rằng với các khối văn bản dài ít ràng buộc về cấu trúc (docstring hoặc comment), độ dài dòng nên giới hạn ở 72 ký tự.

Để kiểm tra mã của bạn có tuân thủ PEP-8 hay không, bạn có thể dùng mô-đun pylint của Python. Mô-đun này có thể dùng để điều chỉnh giới hạn ký tự cho comment và các dòng mã khác.

Hãy xem một vài ví dụ.

• Mô tả khi import mô-đun

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Mô tả khi định nghĩa biến

n_classes = 10 # MNIST total classes (0-9 digits)

Để hiểu sâu hơn về comment và những điều nên/không nên, hãy xem bài viết hữu ích này.

Giờ hãy tìm hiểu cách docstring có thể giúp ghi chép codebase dự án của bạn.

Docstring để ghi chép mã Python

Docstring trong Python là chuỗi tài liệu, một string literal xuất hiện trong định nghĩa lớp, mô-đun, hàm hoặc phương thức và được viết ở dòng đầu tiên. Docstring có thể truy cập qua thuộc tính doc (__doc__) của bất kỳ đối tượng Python nào, và cũng rất hữu ích với hàm tích hợp help().

Bên cạnh đó, Docstring rất hữu ích để hiểu chức năng của phần mã lớn hơn, tức mục đích tổng quát của bất kỳ lớp, mô-đun hay hàm nào. Ngược lại, comment được dùng cho mã, câu lệnh và biểu thức, thường là ngắn. Chúng là văn bản mô tả do lập trình viên viết chủ yếu cho chính họ để biết dòng mã hay biểu thức làm gì, và cho nhà phát triển muốn đóng góp vào dự án. Đây là phần thiết yếu: ghi chép mã sẽ phục vụ tốt cho việc viết mã sạch và chương trình chỉn chu. Dù đã nói, không có tiêu chuẩn hay quy tắc cứng nhắc cho việc này.

Có hai dạng viết Docstring: Docstring một dòng và Docstring nhiều dòng. Đây là dạng tài liệu mà các Nhà khoa học dữ liệu/lập trình viên dùng trong dự án.

• Docstring một dòng là Docstring gói gọn trong một dòng. Bạn có thể dùng một trong hai kiểu dấu nháy, tức ba dấu nháy đơn hoặc ba dấu nháy kép, và dấu mở phải khớp với dấu đóng. Với Docstring một dòng, dấu nháy đóng nằm cùng dòng với dấu nháy mở. Theo thông lệ, dùng ba dấu nháy kép.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Docstring nhiều dòng cũng chứa chuỗi mô tả như Docstring một dòng, nhưng theo sau là một dòng trống và văn bản mô tả chi tiết.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Từ bảng trên, hãy chọn Pydoc như một định dạng docstring và khám phá thêm.

Như bạn đã biết, docstring có thể truy cập thông qua thuộc tính tích hợp __doc__ của Python và hàm help(). Bạn cũng có thể dùng mô-đun tích hợp gọi là Pydoc, rất khác về tính năng & chức năng so với thuộc tính doc và hàm help.

Pydoc là công cụ hữu ích khi bạn muốn chia sẻ mã với đồng nghiệp hoặc mở nguồn, khi đó bạn nhắm tới đối tượng người dùng rộng hơn. Nó có thể tạo trang web từ tài liệu Python của bạn và cũng có thể khởi chạy máy chủ web.

Hãy xem nó hoạt động thế nào.

Cách dễ và tiện nhất để chạy mô-đun Pydoc là chạy như một script. Để chạy trong một ô jupyter lab, bạn sẽ dùng ký tự dấu chấm than (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Nếu bạn nhìn vào đầu ra ở trên, công dụng đầu tiên của Pydoc là hiển thị tài liệu dạng văn bản cho một hàm, mô-đun, lớp, v.v. vậy hãy xem cách bạn có thể tận dụng điều đó tốt hơn so với hàm help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Giờ, hãy trích xuất tài liệu của glob bằng hàm help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Như bạn thấy, nó báo lỗi name error vì glob chưa được định nghĩa. Vậy để dùng hàm help để trích xuất tài liệu, trước tiên bạn phải import mô-đun đó, điều này không bắt buộc với Pydoc.

Hãy khám phá tính năng thú vị nhất của mô-đun Pydoc, tức chạy Pydoc như một dịch vụ web.

Để làm điều này, bạn chỉ cần chạy Pydoc như một script nhưng kèm tham số -b, tham số này sẽ khởi chạy một máy chủ HTTP trên một cổng không dùng bất kỳ và mở trình duyệt web để duyệt tài liệu tương tác. Điều này hữu ích đặc biệt khi bạn có nhiều dịch vụ khác đang chạy và không nhớ cổng nào đang rảnh.

!python -m pydoc -b

^C

Ngay khi chạy ô trên, một cửa sổ mới sẽ mở ở một số cổng ngẫu nhiên và trình duyệt web sẽ trông giống như hình dưới đây.

Hãy xem tài liệu của mô-đun h5py, một định dạng tệp dùng để lưu trọng số của kiến trúc mạng nơ-ron.

Những điều cốt yếu khi ghi chép dự án Python

Bất kể mục tiêu, tầm nhìn và mục đích của dự án, tài liệu của mọi dự án nhìn chung là tương tự. Dự án có thể thuộc các loại sau:

• Dự án riêng tư (cá nhân): Có thể để xây dựng portfolio hoặc làm freelancer duy trì kho GitHub.

• Dự án hợp tác (theo nhóm): Có thể là dự án đang chạy trong tổ chức của bạn hoặc tham gia một cuộc thi Kaggle.

• Dự án mã nguồn mở: Tập trung vào việc chia sẻ với đối tượng rộng. Kỳ vọng có sự hợp tác, đóng góp và khả năng duy trì codebase cũng như tài liệu về lâu dài.

Dù ba loại dự án trên có tầm nhìn khác nhau, mẫu tài liệu có thể dùng chung cho mọi loại dự án.

Giả sử bạn đang làm một dự án mã nguồn mở và cần tạo một kho GitHub cho dự án với tài liệu chi tiết, cập nhật thường xuyên, dưới đây là các điểm thiết yếu cần lưu ý:

• Tệp requirements: Nhiều tác giả hay quên, nhưng tệp requirements rất quan trọng. Nó giúp người dùng tái tạo mã của bạn nhanh chóng. Thông thường là tệp văn bản chứa toàn bộ gói, mô-đun cùng phiên bản tương ứng đã dùng trong dự án. Yêu cầu cũng có thể nêu trong tệp Readme, nhưng tách riêng luôn tốt hơn vì người dùng chỉ cần chạy tệp đó với lệnh pip là toàn bộ phụ thuộc sẽ được cài trên hệ thống của họ.

• Readme: Readme thường ở định dạng markdown, và cũng là xương sống của nhiều dự án. Tóm tắt dự án, tính năng, mục đích cùng logo đẹp. Nên bao gồm hướng dẫn cài đặt hoặc vận hành dự án. Bổ sung các thay đổi đáng kể so với phiên bản trước. Các script kiểm thử hoặc một tour nhanh để chạy mã thành công trong Readme sẽ giúp người dùng tự tin theo đuổi dự án của bạn hơn. Nó cũng có thể nêu bật các vấn đề tiềm ẩn mà người dùng có thể gặp.

• Cách cộng tác: Rất quan trọng, đặc biệt khi làm dự án mã nguồn mở. Phần này nên nêu cách cộng tác viên mới có thể đóng góp cho dự án: phát triển tính năng mới, sửa lỗi đã biết, bổ sung tài liệu, thêm kiểm thử mới, hoặc báo cáo sự cố. Cộng tác viên thậm chí có thể phát hành bản v2.0 của cùng dự án và đưa nó lên tầm cao mới.

• Giấy phép: Tệp văn bản thuần mô tả giấy phép mà dự án của bạn sử dụng. Đặc biệt quan trọng với dự án mã nguồn mở, như Boost, Apache, MIT, v.v. Điều này cho người dùng biết dự án có được dùng cho mục đích thương mại hay mức độ cho phép đến đâu.

• Phân công nhiệm vụ: Nếu bạn đang làm dự án chia sẻ như Kaggle, bạn có thể xác định nhiệm vụ mỗi thành viên được giao và mức tiến độ. Điều này giúp theo dõi tiến độ tổng thể của dự án.

• Tái sử dụng khung làm việc: Rất quan trọng trong dự án chia sẻ như Kaggle, nơi đồng đội có thể tái sử dụng những gì bạn đã xây dựng, tiết kiệm nhiều thời gian. Ví dụ: pipeline tiền xử lý dữ liệu, script cross-validation dữ liệu, v.v.

Một tài liệu được khuyến nghị cao, có cấu trúc rất tốt và có thể là ví dụ hoàn hảo về cách một dự án mã nguồn mở nên trông như thế nào, hãy xem kho GitHub transformers của huggingface.

Kết luận

Chúc mừng bạn đã hoàn thành hướng dẫn.

Một bài tập hay cho tất cả là khám phá thêm mô-đun Pydoc và các định dạng docstring khác của Python như Epydoc và Google docstrings để tìm ra chúng khác nhau thế nào.

Vui lòng đặt câu hỏi liên quan đến hướng dẫn này trong phần bình luận bên dưới.

Tài liệu tham khảo:

• Docstring trong Python

Nếu bạn mới bắt đầu với Python và muốn học thêm, hãy tham gia khóa Intermediate Python của DataCamp.