Sample prompt for creating source code documentation.

In software development, source code documentation is just as important as the code itself. A well-built system lacking clear documentation will hinder maintenance, expansion, and collaboration among team members. However, documentation is often overlooked due to its time-consuming nature and potential for inconsistency.

 

The emergence of artificial intelligence has opened up a more efficient approach: using prompts to automate and standardize the code documentation process. Through well-designed prompt templates, programmers can quickly create detailed descriptions of functionality, system structure, processing flow, and API usage while ensuring clarity and consistency.

The source code documentation prompt template focuses on building and implementing high-quality prompts to support the documentation process effectively. This is not only a time-saving solution but also contributes to improving the quality of software products, helping development teams work more efficiently and sustainably.

Sample prompt for creating source code documentation.

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]

Best suited for: Claude 4 Sonnet, GPT-5

Instructions for using the sample prompt.

1. Replace [PASTE CODE OR FUNCTION] with the code you want to use to create a reference.
2. Select the format as XML Annotations.

The example prompt is a sample execution using 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

Below is the detailed XML document for the OrderService as requested:

 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. 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. 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. Đối tượng người dùng tạo đơn hàng. 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 } Đối tượng Order đã được tạo, bao gồm các OrderItem liên quan và tổng giá trị đơn hàng. Tạo Order với trạng thái ban đầu là "PENDING" Khởi tạo tổng giá trị đơn hàng = 0 Duyệt qua từng item trong danh sách Lấy thông tin Product từ database Kiểm tra tồn kho Nếu đủ hàng: Giảm số lượng tồn kho Lưu Product Tạo OrderItem Cộng dồn total_price Cập nhật total_price cho Order Lưu Order Trả về Order Xảy ra khi product_id không tồn tại trong hệ thống. Xảy ra khi số lượng yêu cầu vượt quá tồn kho ("Not enough stock"). Xảy ra khi thiếu key "product_id" hoặc "quantity" trong item. Có thể xảy ra khi thao tác với database thất bại. Hiện tại hàm không xử lý exception nội bộ mà để propagate ra ngoài. Khuyến nghị: Sử dụng transaction.atomic() để đảm bảo tính toàn vẹn dữ liệu Bắt và log exception tại tầng higher-level (view/service layer)  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)   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).  O(1) (không tính bộ nhớ database). Bộ nhớ sử dụng không tăng đáng kể theo input. 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. Nên tối ưu bằng cách preload products để tránh N+1 query problem. Nên validate input trước khi xử lý (quantity > 0).