Mẫu prompt tạo tài liệu code nguồn

Trong quá trình phát triển phần mềm, tài liệu code nguồn đóng vai trò quan trọng không kém gì bản thân mã lệnh. Một hệ thống được xây dựng tốt nhưng thiếu tài liệu rõ ràng sẽ gây khó khăn cho việc bảo trì, mở rộng và cộng tác giữa các thành viên trong nhóm. Tuy nhiên, việc viết tài liệu thường bị xem nhẹ do tốn thời gian và dễ trở nên không nhất quán.

Sự xuất hiện của trí tuệ nhân tạo đã mở ra một hướng tiếp cận hiệu quả hơn: Sử dụng prompt để tự động hóa và chuẩn hóa quá trình tạo tài liệu code. Thông qua các mẫu prompt được thiết kế hợp lý, lập trình viên có thể nhanh chóng tạo ra các mô tả chi tiết về chức năng, cấu trúc hệ thống, luồng xử lý và cách sử dụng API mà vẫn đảm bảo tính rõ ràng và đồng bộ.

Mẫu prompt tạo tài liệu code nguồn tập trung vào việc xây dựng và áp dụng các prompt chất lượng nhằm hỗ trợ quá trình tài liệu hóa một cách hiệu quả. Đây không chỉ là giải pháp tiết kiệm thời gian mà còn góp phần nâng cao chất lượng sản phẩm phần mềm, giúp đội ngũ phát triển làm việc hiệu quả và bền vững hơn.

Mẫu prompt tạo tài liệu code nguồn

Tạo tài liệu toàn diện cho:

[DÁN CODE HOẶC HÀM]

Bao gồm:
- Mô tả hàm/lớp
- Tài liệu tham số
- Tài liệu giá trị trả về
- Ví dụ sử dụng
- Các trường hợp ngoại lệ và xử lý lỗi
- Độ phức tạp về thời gian/không gian

Định dạng: [JSDoc / Docstring / Chú thích XML]

Phù hợp nhất cho: Claude 4 Sonnet, GPT-5

Hướng dẫn sử dụng prompt mẫu

1. Thay thế [DÁN CODE HOẶC HÀM] bằng code bạn muốn tạo tài liệu tham khảo.
2. Chọn định dạng là Chú thích XML.

Ví dụ prompt mẫu được thực hiện bằng GPT-5

Tạo tài liệu toàn diện cho:

# services/order_service.py

from typing import List
from myapp.models import Order, OrderItem, Product

class OrderService:
    """
    Service xử lý logic liên quan đến đơn hàng
    """

    def create_order(self, user, items: List[dict]) -> Order:
        """
        Tạo đơn hàng mới

        :param user: User object
        :param items: List dict gồm product_id và quantity
        :return: Order
        """
        order = Order.objects.create(user=user, status="PENDING")

        total_price = 0

        for item in items:
            product = Product.objects.get(id=item["product_id"])

            if product.stock < item["quantity"]:
                raise ValueError("Not enough stock")

            product.stock -= item["quantity"]
            product.save()

            OrderItem.objects.create(
                order=order,
                product=product,
                quantity=item["quantity"],
                price=product.price
            )

            total_price += product.price * item["quantity"]

        order.total_price = total_price
        order.save()

        return order

Bao gồm:
- Mô tả hàm/lớp
- Tài liệu tham số
- Tài liệu giá trị trả về
- Ví dụ sử dụng
- Các trường hợp ngoại lệ và xử lý lỗi
- Độ phức tạp về thời gian/không gian

Định dạng: Chú thích XML

Dưới đây là tài liệu XML chi tiết cho OrderService theo yêu cầu:

<document>
    <module name="services.order_service">
        <description>
            Module cung cấp service xử lý logic liên quan đến đơn hàng trong hệ thống.
            Bao gồm việc tạo đơn hàng, kiểm tra tồn kho, và tính toán tổng giá trị đơn hàng.
        </description>

        <class name="OrderService">
            <description>
                Service chịu trách nhiệm xử lý các nghiệp vụ liên quan đến đơn hàng.
                Tách biệt logic khỏi view/controller để tăng khả năng bảo trì và tái sử dụng.
            </description>

            <method name="create_order">
                <description>
                    Tạo một đơn hàng mới cho người dùng dựa trên danh sách sản phẩm.
                    Thực hiện kiểm tra tồn kho, cập nhật số lượng sản phẩm, và tính tổng giá trị đơn hàng.
                </description>

                <parameters>
                    <param name="user" type="User">
                        Đối tượng người dùng tạo đơn hàng.
                    </param>
                    <param name="items" type="List[dict]">
                        Danh sách các sản phẩm cần đặt hàng.
                        Mỗi phần tử là một dictionary có cấu trúc:
                        {
                            "product_id": int,
                            "quantity": int
                        }
                    </param>
                </parameters>

                <returns type="Order">
                    Đối tượng Order đã được tạo, bao gồm các OrderItem liên quan và tổng giá trị đơn hàng.
                </returns>

                <workflow>
                    <step>Tạo Order với trạng thái ban đầu là "PENDING"</step>
                    <step>Khởi tạo tổng giá trị đơn hàng = 0</step>
                    <step>Duyệt qua từng item trong danh sách</step>
                    <step>Lấy thông tin Product từ database</step>
                    <step>Kiểm tra tồn kho</step>
                    <step>Nếu đủ hàng:
                        <substep>Giảm số lượng tồn kho</substep>
                        <substep>Lưu Product</substep>
                        <substep>Tạo OrderItem</substep>
                        <substep>Cộng dồn total_price</substep>
                    </step>
                    <step>Cập nhật total_price cho Order</step>
                    <step>Lưu Order</step>
                    <step>Trả về Order</step>
                </workflow>

                <exceptions>
                    <exception type="Product.DoesNotExist">
                        Xảy ra khi product_id không tồn tại trong hệ thống.
                    </exception>
                    <exception type="ValueError">
                        Xảy ra khi số lượng yêu cầu vượt quá tồn kho ("Not enough stock").
                    </exception>
                    <exception type="KeyError">
                        Xảy ra khi thiếu key "product_id" hoặc "quantity" trong item.
                    </exception>
                    <exception type="DatabaseError">
                        Có thể xảy ra khi thao tác với database thất bại.
                    </exception>
                </exceptions>

                <error_handling>
                    <strategy>
                        Hiện tại hàm không xử lý exception nội bộ mà để propagate ra ngoài.
                        Khuyến nghị:
                        <item>Sử dụng transaction.atomic() để đảm bảo tính toàn vẹn dữ liệu</item>
                        <item>Bắt và log exception tại tầng higher-level (view/service layer)</item>
                    </strategy>
                </error_handling>

                <example>
                    <code language="python">
from services.order_service import OrderService

service = OrderService()

order = service.create_order(
    user=request.user,
    items=[
        {"product_id": 1, "quantity": 2},
        {"product_id": 3, "quantity": 1}
    ]
)

print(order.id)
print(order.total_price)
                    </code>
                </example>

                <complexity>
                    <time>
                        O(n) với n là số lượng items trong đơn hàng.
                        Tuy nhiên, do mỗi lần lặp có truy vấn database (Product.objects.get),
                        nên thực tế là O(n) queries (có thể tối ưu bằng bulk query).
                    </time>
                    <space>
                        O(1) (không tính bộ nhớ database).
                        Bộ nhớ sử dụng không tăng đáng kể theo input.
                    </space>
                </complexity>

                <notes>
                    <note>
                        Có thể xảy ra race condition khi nhiều request cùng cập nhật stock.
                        Nên sử dụng select_for_update() hoặc locking.
                    </note>
                    <note>
                        Nên tối ưu bằng cách preload products để tránh N+1 query problem.
                    </note>
                    <note>
                        Nên validate input trước khi xử lý (quantity &gt; 0).
                    </note>
                </notes>

            </method>
        </class>
    </module>
</document>