AI đã thay đổi những gì các kỹ sư cần tự ghi chép. GitHub Copilot, Cursor và Mintlify có thể tạo ra các tài liệu ban đầu: mô tả tham số, tóm tắt hàm và khung sườn README. Điều mà chúng không thể viết là Lớp Ý định: quyết định đã đưa ra, sự đánh đổi đã chấp nhận, ràng buộc quan trọng và lựa chọn mà nhóm đã từ chối.
Mã thể hiện hành vi. Nó hiếm khi ghi lại lý do. Lý do đó thường nằm trong một chủ đề trên Slack, bình luận trên ticket, báo cáo sự cố, hoặc trong trí nhớ của ai đó.
Cuộc khảo sát nhà phát triển năm 2024 của Stack Overflow cho thấy 61% nhà phát triển chuyên nghiệp dành hơn 30 phút mỗi ngày để tìm kiếm câu trả lời trong công việc, trong đó một phần tư số người dành hơn một giờ. Tất nhiên, một số việc tìm kiếm là không thể tránh khỏi. Nhưng sự lãng phí thực sự nằm ở bối cảnh của các đợt sprint mà chưa bao giờ được ghi lại trong tài liệu.
Hướng dẫn này chỉ ra những nội dung mà các kỹ sư nên tự viết, những phần mà AI có thể hỗ trợ, và cách duy trì tính hữu ích của tài liệu mã nguồn sau khi sprint kết thúc.
Tóm tắt
AI có thể soạn thảo phần cơ bản của tài liệu: docstrings, kiểu tham số, tóm tắt hàm và khung sườn cho tệp README. Các kỹ sư vẫn cần viết phần nội dung ý định: các quyết định, sự đánh đổi, hạn chế và các phương án bị loại bỏ đằng sau mã.
Các kỹ sư vẫn nên tự viết những nội dung này trong các Bản ghi Quyết định Kiến trúc (Architecture Decision Records), mô tả pull request (PR) và các bình luận giải thích (why-comments) được commit cùng với mã nguồn. Lớp ý định này giúp ngăn chặn việc nhà phát triển tiếp theo phải phân tích ngược các quyết định từ tên biến, thông điệp commit và các pull request cũ. Trí tuệ nhân tạo (AI) hiện có thể soạn thảo các phần thường lệ: kiểu tham số, mô tả giá trị trả về và tóm tắt hàm cơ bản.
Tài liệu mã thực sự nên giải thích những gì?
Tài liệu mã nguồn nên giúp các nhà phát triển tiếp theo hiểu được chức năng của mã, cách sử dụng an toàn và lý do tại sao nó được xây dựng như vậy. Tài liệu này xuất hiện ở hai nơi: bên trong các tệp nguồn dưới dạng bình luận và chuỗi tài liệu (docstrings), và bên ngoài các tệp nguồn dưới dạng tệp README, tài liệu tham khảo API, tài liệu hướng dẫn vận hành (runbooks) và ghi chú kiến trúc.
Hầu hết các cơ sở mã trở nên khó đọc sau khi bối cảnh ra quyết định biến mất. Nhà phát triển ban đầu có thể đã thực hiện một sự cân bằng thông minh. Nhà phát triển tiếp theo chỉ nhìn thấy sản phẩm, chứ không phải lý do đằng sau nó.
Kết quả là: mỗi thành viên mới trong nhóm phải tự phân tích ý định từ tên biến, thông điệp commit và các PR cũ. Điều này làm chậm quá trình onboarding, đánh giá, gỡ lỗi và các thay đổi trong tương lai đối với cùng một khu vực.
Một tài liệu tốt phải trả lời được bốn câu hỏi:
- Mã nguồn này dành cho ai? Các nhà phát triển nội bộ, những người đóng góp mã nguồn mở, người sử dụng API bên ngoài hay người dùng cuối
- Nó giải quyết vấn đề gì? Nhu cầu kinh doanh hoặc kỹ thuật đằng sau mô-đun
- Tại sao lại chọn phương pháp này? Các phương án thay thế đã được xem xét và những sự đánh đổi đã được chấp nhận
- Các thành phần liên quan nằm ở đâu? Các mô-đun phụ thuộc, dịch vụ cấp trên, quyết định kiến trúc, phiếu yêu cầu và tài liệu hướng dẫn vận hành
Câu hỏi “tại sao” xứng đáng nhận được sự quan tâm nhiều nhất từ con người.
Tìm kiếm cũng đã trở thành một gánh nặng lớn đối với công việc trí óc ngoài lĩnh vực kỹ thuật. Cuộc khảo sát về quản lý kiến thức của ClickUp cho thấy 57% nhân viên lãng phí thời gian tìm kiếm tài liệu nội bộ hoặc cơ sở kiến thức để tìm kiếm thông tin liên quan đến công việc. Khi không thể tìm thấy những gì họ cần, 1 trong 6 người phải dùng đến các biện pháp thay thế cá nhân: lục lọi các email, ghi chú hoặc ảnh chụp màn hình cũ.
Tài liệu mã cũng gặp vấn đề tương tự: nếu các nhà phát triển không thể tìm thấy lời giải thích, thì lời giải thích đó cũng như không tồn tại.
Hậu quả của việc làm sai là rất nặng nề. Một người bình luận trên r/AskProgramming đã mô tả một quy trình làm việc RPA, trong đó một nút bấm không được ghi chú suýt nữa đã kích hoạt các khoản phí ngân hàng tự động hóa và thư gửi khách hàng.
Tìm kiếm cũng đã trở thành một gánh nặng lớn đối với công việc trí óc ngoài lĩnh vực kỹ thuật. Cuộc khảo sát về quản lý kiến thức của ClickUp cho thấy 57% nhân viên lãng phí thời gian tìm kiếm tài liệu nội bộ hoặc cơ sở kiến thức để tìm kiếm thông tin liên quan đến công việc. Khi không thể tìm thấy những gì họ cần, 1 trong 6 người phải dùng đến các biện pháp thay thế cá nhân: lục lọi các email, ghi chú hoặc ảnh chụp màn hình cũ.
Tài liệu mã cũng gặp vấn đề tương tự: nếu các nhà phát triển không thể tìm thấy lời giải thích, thì lời giải thích đó cũng như không tồn tại.
Hậu quả của việc làm sai là rất nặng nề. Một người bình luận trên r/AskProgramming đã mô tả một quy trình làm việc RPA trong đó một nút bấm không được ghi chú suýt nữa đã kích hoạt các khoản phí ngân hàng tự động hóa và thư gửi khách hàng.
Các loại tài liệu mã chính là gì?
Có năm loại chính là chú thích trong mã, docstring, tệp README, wiki nội bộ và tài liệu API bên ngoài. Mỗi loại phục vụ một đối tượng độc giả khác nhau vào những thời điểm khác nhau. Việc trộn lẫn chúng sẽ khiến tài liệu khó viết và khó sử dụng hơn. Một tệp README được viết giống như một docstring sẽ làm mất đi những người đóng góp mới. Một docstring được viết giống như một trang wiki sẽ trở thành gánh nặng trong các tệp nguồn.
Chú thích trong dòng và docstrings
Các bình luận trong dòng nên giải thích các lý do không rõ ràng. Một bình luận diễn giải lại x = x + 1 thành “tăng x lên 1” không mang lại giá trị gì. Một bình luận ghi “điều chỉnh cho phản hồi API có chỉ mục bắt đầu từ 0” là cần thiết vì mã nguồn không thể thể hiện ràng buộc bên ngoài đó. Hãy dành các bình luận trong dòng cho các logic không rõ ràng bên trong thân hàm.
Docstrings là các mô tả có cấu trúc được gắn vào các hàm, lớp hoặc mô-đun. Chúng bao gồm các tham số, giá trị trả về, ngoại lệ và các ví dụ sử dụng. Mỗi ngôn ngữ có các quy ước riêng. Hãy tuân theo quy ước mà ngôn ngữ của bạn đã quy định: PEP 257 cho docstrings của Python, Javadoc cho Java và JSDoc cho JavaScript và TypeScript.
Hãy so sánh hai điều sau:
Docstring yếu:
Docstring mạnh mẽ:
Tên hàm thứ hai được đặt rõ ràng, ghi chú các tham số của nó và nêu rõ một giả định: luồng thanh toán sử dụng mức thuế 8,25%.
README, wiki và tài liệu bên ngoài
Một tệp README cần trả lời năm câu hỏi theo thứ tự: Dự án này làm gì? Làm thế nào để cài đặt nó? Làm thế nào để sử dụng nó? Làm thế nào để đóng góp? Nơi nào để nhận hỗ trợ? Nếu một người đóng góp mới không thể tìm thấy đường dẫn thiết lập một cách nhanh chóng, thì tệp README hoặc là quá tải thông tin hoặc là được sắp xếp không hợp lý.
Các trang wiki và cơ sở kiến thức hoạt động hiệu quả nhất với nội dung trải rộng trên nhiều kho lưu trữ hoặc dịch vụ: các quyết định về kiến trúc, hướng dẫn nhập môn và sổ tay vận hành. Một trang wiki mà không ai liên kết từ mã nguồn sẽ trở thành một vấn đề tìm kiếm thứ hai.
Tài liệu bên ngoài bao gồm tài liệu tham khảo API, hướng dẫn SDK và tài liệu dành cho người dùng. Nó phục vụ những người sử dụng mã nguồn của bạn, chứ không phải những người đóng góp. Tài liệu bên ngoài cần có nhiều chi tiết thiết lập hơn, các bước xác thực rõ ràng hơn và cấu trúc theo kiểu tài liệu tham khảo vì người đọc có thể hoàn toàn không biết gì về cơ sở mã nguồn của bạn.
Nếu nhóm chưa có cấu trúc, hãy bắt đầu với mẫu tài liệu kỹ thuật về kiến trúc và ghi chú thiết lập, hoặc mẫu tài liệu dự án về mục tiêu, người chịu trách nhiệm, các cột mốc quan trọng và quyết định. Hãy điều chỉnh các phần thay vì tạo ra một định dạng hoàn toàn mới.
| Loại | Đối tượng chính | Tần suất cập nhật | Địa điểm điển hình |
|---|---|---|---|
| Bình luận trong dòng | Các nhà phát triển đang xem xét một đường dẫn mã cụ thể | Khi hành vi của mã thay đổi | Tệp nguồn |
| Docstrings | Các nhà phát triển gọi một hàm, lớp hoặc mô-đun | Khi giao diện thay đổi | Tệp nguồn |
| README | Những người đóng góp và đánh giá mới | Theo từng bản phát hành chính hoặc thay đổi dự án | Kho lưu trữ gốc |
| Wiki hoặc cơ sở kiến thức | Các nhóm nội bộ và các bên liên quan giữa các nhóm | Khi các quyết định hoặc quy trình thay đổi | Wiki kho lưu trữ hoặc cơ sở kiến thức chung |
| Tài liệu API bên ngoài | Người dùng API và người dùng cuối | Theo từng bản phát hành hoặc phiên bản API | Nền tảng tài liệu |
Hiện nay, bạn thực sự viết tài liệu như thế nào?
Sử dụng AI cho những phần mà nó có thể soạn thảo. Dành thời gian của con người cho các quyết định, hạn chế và sự đánh đổi.
AI hiện có thể soạn thảo phần lớn các công việc cơ bản: kiểu tham số, mô tả giá trị trả về và tóm tắt hàm cơ bản. Công việc tài liệu hóa do con người thực hiện được chia thành hai loại.
Viết mã tự giải thích trước tiên
Tài liệu tốt nhất là mã nguồn hầu như không cần đến tài liệu. Các tên mô tả, hàm đơn mục đích và các quy ước nhất quán giúp giảm bớt gánh nặng tài liệu ngay từ khi bạn chưa viết bất kỳ bình luận nào.
Mã nguồn tự giải thích giúp hành vi của mã dễ đọc hơn. Tuy nhiên, nó hiếm khi giải thích lý do đằng sau hành vi đó. Tên gọi giúp các nhà phát triển nhận biết chức năng của một thành phần. Tài liệu nên giải thích những lý do mà tên gọi không thể truyền tải.
Trước khi thêm một bình luận, hãy tự hỏi liệu việc đổi tên biến hoặc tách hàm ra có làm cho bình luận đó trở nên thừa thãi hay không. Nếu câu trả lời là có, hãy tiến hành refactor trước. Một tên gọi rõ ràng sẽ loại bỏ những bình luận chỉ nhằm giải thích cho việc đặt tên không tốt.
Trước đây:
Sau:
Phiên bản được tái cấu trúc truyền đạt cùng thông tin chỉ thông qua cách đặt tên. Lúc này, bình luận hữu ích duy nhất sẽ giải thích lý do tại sao một số vai trò bị loại trừ, đây là quyết định chính sách mà mã nguồn không thể tự thể hiện được.
Viết phần ý định (phần mà AI không thể làm)
Việc triển khai được hiển thị trong mã nguồn. Ý định sẽ biến mất trừ khi ai đó ghi chép lại. Mã nguồn hiếm khi ghi lại lý do tại sao một sự đánh đổi được thực hiện, ràng buộc nào đã định hướng thiết kế, hoặc phương án thay thế nào đã bị loại bỏ.
Một quy tắc phổ biến của các nhà phát triển tóm tắt điều này rất hay: hãy ghi chép lý do, chứ không phải nội dung. Một bình luận được bình chọn nhiều nhất trên r/coding:
Tôi thấy rằng nhánh điều kiện này phân chia giữa người dùng màu đỏ và màu xanh. Hãy giải thích tại sao người dùng được phân loại như vậy và tại sao chúng ta lại phân nhánh giữa hai nhóm này.
Tôi thấy rằng nhánh điều kiện này phân chia giữa người dùng màu đỏ và màu xanh. Hãy giải thích tại sao người dùng lại được phân loại như vậy và tại sao chúng ta lại phân nhánh giữa hai nhóm này.
Một thông điệp commit có thể hữu ích trong quá trình xem xét, nhưng nó không phải là nơi lưu trữ lý do thiết kế lâu dài vì những người đọc sau này hiếm khi tìm thấy nó vào thời điểm họ cần.
Will Larson, cựu Giám đốc Công nghệ (CTO) của Calm và tác giả cuốn An Elegant Puzzle, đã viết về giá trị của Hồ sơ Quyết định Kiến trúc vì chúng giúp lưu giữ cơ sở lý luận kỹ thuật bên ngoài cơ sở mã nguồn.
ADR rất hữu ích vì chúng cung cấp một nền tảng ổn định cho lý do thiết kế. Nếu nhóm của bạn chưa có định dạng, hãy tham khảo một mẫu ADR đơn giản: quyết định, bối cảnh, các phương án được xem xét, sự đánh đổi và hậu quả.
Hãy tập trung tài liệu của bạn vào các danh mục sau:
- Quyết định thiết kế và các phương án thay thế: “Chúng tôi đã chọn bộ nhớ đệm ghi qua (write-through cache) thay vì ghi lại (write-back) ở đây vì tính nhất quán của dữ liệu quan trọng hơn độ trễ ghi đối với luồng thanh toán này”
- Những giới hạn đã biết: Nợ kỹ thuật, giới hạn về khả năng mở rộng, các giải pháp tạm thời hoặc các lĩnh vực cần được khắc phục trong tương lai
- Giả định: Các định dạng đầu vào dự kiến, yêu cầu về môi trường hoặc các phụ thuộc ở giai đoạn trước mà mã nguồn không bắt buộc
- Tham khảo: Các liên kết đến các ticket, RFC hoặc Bản ghi quyết định kiến trúc (ADR) liên quan giải thích bối cảnh rộng hơn
Các bối cảnh khác nhau cần các vị trí lưu trữ khác nhau. Docstrings ghi lại ý định ở cấp độ hàm. Lời bình luận mã xử lý lý do ở cấp độ dòng. Mô tả PR cung cấp bối cảnh ở cấp độ thay đổi. ADRs xử lý các quyết định ở cấp độ hệ thống. Thông điệp commit cũng hữu ích, nhưng chúng không nên là bản ghi duy nhất của một quyết định quan trọng.
Một mô hình sai lầm phổ biến: ghi chép cách thức hoạt động của thuật toán sắp xếp theo từng dòng mã. Câu hỏi thực sự là tại sao lại sử dụng thuật toán sắp xếp tùy chỉnh thay vì thư viện chuẩn. Đối với các đường dẫn mã tùy chỉnh, hãy ghi chép lý do đằng sau quyết định triển khai đó.
Những nguyên tắc tốt nhất quan trọng nhất trong việc lập tài liệu là gì?
Năm thói quen giúp tài liệu có khả năng duy trì tính hữu ích sau khi sprint kết thúc. Hầu hết các lời khuyên khác về tài liệu đều phụ thuộc vào việc những thói quen này được thực hiện trước tiên.
- Hãy ghi chú ngay khi viết mã, đừng để đến sau. Bối cảnh thay đổi rất nhanh. Đến đợt sprint tiếp theo, bạn đã quên mất phương án nào đã bị loại bỏ và lý do tại sao. Hãy ghi chú lý do trong cùng một commit với mã nguồn, nếu không bạn sẽ không bao giờ ghi chú được.
- Sử dụng hướng dẫn phong cách nhất quán. Chọn một định dạng docstring, chẳng hạn như phong cách Google, NumPy, Javadoc hoặc JSDoc, và áp dụng nó trong quá trình kiểm tra mã nguồn hoặc linting. Sự nhất quán quan trọng hơn việc bạn chọn định dạng nào. Một hướng dẫn phong cách chung sẽ loại bỏ câu hỏi “Tôi nên định dạng phần này như thế nào?” và giúp việc tự động hóa linting trở nên khả thi
- Xem tài liệu như một phần của quá trình kiểm tra mã nguồn. Thêm các kiểm tra tài liệu vào danh sách kiểm tra PR của bạn. Nếu một PR thay đổi hành vi, người kiểm tra nên xác minh xem tài liệu có phản ánh sự thay đổi đó hay không. Tài liệu về Thực hành Kỹ thuật của Google yêu cầu người kiểm tra xác minh xem mã nguồn có được tài liệu hóa phù hợp hay không. Áp dụng quy tắc tương tự trong nội bộ: nếu một PR thay đổi hành vi, người kiểm tra nên xác minh xem các bình luận, docstrings, READMEs và runbooks vẫn còn phù hợp hay không
- Xóa bỏ tài liệu lỗi thời. Tài liệu lỗi thời gây ra tác hại thực sự vì chúng dẫn người đọc đến các phương án triển khai, API hoặc quy trình sai. Hãy rà soát tài liệu hàng quý hoặc trước mỗi bản phát hành lớn. Chỉ định người có quyền sở hữu để việc quản lý tài liệu không trở thành trách nhiệm chung của mọi người và do đó không ai chịu trách nhiệm.
- Đảm bảo các ví dụ có thể chạy được. Các ví dụ mã nguồn nên dễ sao chép, chạy và kiểm thử. Đó là cách an toàn nhất để phát hiện sự sai lệch trước khi người dùng phát hiện ra.
Bạn nên sử dụng công cụ nào để tạo tài liệu mã?
Các công cụ tài liệu được chia thành hai nhóm: các công cụ tạo tài liệu truyền thống và trợ lý AI. Chúng đảm nhận các nhiệm vụ khác nhau.
Các công cụ tạo tài liệu truyền thống phân tích các bình luận có cấu trúc trong mã nguồn của bạn và tạo ra các tài liệu tham khảo có thể duyệt qua. Công cụ tạo tài liệu phù hợp thường phụ thuộc vào ngôn ngữ lập trình của bạn.
| Công cụ | Ngôn ngữ/Hệ sinh thái | Nó tạo ra những gì |
|---|---|---|
| Javadoc | Java | Tham chiếu API từ các bình luận trong tài liệu |
| JSDoc | JavaScript/TypeScript | Tham chiếu API từ các bình luận có chú thích |
| Sphinx | Python (hỗ trợ các ngôn ngữ khác thông qua plugin) | Các trang tài liệu đầy đủ từ reStructuredText hoặc markdown |
| Doxygen | C, C++, Java, Python và các ngôn ngữ khác | Tài liệu tham khảo đa ngôn ngữ |
| Godoc | Bắt đầu | Tài liệu gói từ các bình luận trong mã nguồn |
Chất lượng đầu ra hoàn toàn phụ thuộc vào các docstring của bạn. Chúng định dạng và xuất bản những gì bạn đã viết. Chúng không tự ý thêm vào những ý định còn thiếu.
Các trợ lý được hỗ trợ bởi AI bổ sung một lớp chức năng thứ hai. GitHub Copilot, Cursor và Windsurf có thể soạn thảo các bình luận và chuỗi văn bản tài liệu (docstrings) ngay trong trình chỉnh sửa. Mintlify có thể giúp tạo và duy trì tài liệu dành cho nhà phát triển từ mã nguồn và tài liệu hiện có. Swimm tập trung vào việc duy trì sự liên kết giữa tài liệu nội bộ và các thay đổi trong mã nguồn. ReadMe và GitBook hỗ trợ các nhóm xuất bản tài liệu tham khảo API và tài liệu dành cho nhà phát triển, thường đi kèm với các tính năng tìm kiếm hoặc soạn thảo được hỗ trợ bởi AI.
Nghiên cứu của Stack Overflow cho thấy tài liệu là danh mục tự động hóa bằng AI được yêu cầu nhiều nhất, được đề cập trong khoảng 33,9% câu trả lời mở của các nhà phát triển. Các công cụ này phát huy hiệu quả nhất khi mã nguồn đã thể hiện rõ ràng hành vi của nó.
AI sẽ kém hiệu quả hơn khi lời giải thích phụ thuộc vào các quyết định được đưa ra bên ngoài cơ sở mã nguồn: một chủ đề trên Slack, một cuộc họp kế hoạch, một phiếu yêu cầu hỗ trợ hoặc một cuộc đánh giá sự cố. AI có thể tóm tắt hàm. Tuy nhiên, AI không thể biết được ràng buộc nào có thể thương lượng, tùy chọn nào bị từ chối, hoặc lý do tại sao sự đánh đổi đó được chấp nhận.
Quy trình làm việc thực tế:
- Hãy để AI soạn thảo khung cơ bản: tóm tắt hàm, tham số, giá trị trả về và các trường hợp ngoại lệ phổ biến
- So sánh với hành vi thực tế của mã
- Thêm lý do: quyết định, hạn chế, giả định hoặc phương án thay thế bị loại bỏ
- Viết ADR cho các quyết định cấp hệ thống
- Không nên công bố tài liệu do AI tạo ra mà không qua kiểm duyệt
ClickUp phù hợp ở đâu và không phù hợp ở đâu
ClickUp không phải là công cụ tạo tài liệu ở cấp độ mã nguồn. Nó sẽ không thay thế Javadoc, Sphinx, JSDoc hay Godoc. Nó hỗ trợ việc lập tài liệu xung quanh mã nguồn: READMEs, runbooks, hướng dẫn onboarding, ADRs và nhật ký quyết định, những tài liệu này cần được kết nối chặt chẽ với các công việc, ticket và sprint đã tạo ra chúng.
ClickUp Docs cho phép bạn soạn thảo các tài liệu này song song với công việc kỹ thuật của mình, và ClickUp Brain có thể soạn thảo một tài liệu dựa trên bối cảnh của công việc hoặc dự án, sau đó các nhà phát triển có thể bổ sung lý do ra quyết định, các ràng buộc và các sự đánh đổi.
Đối với các nhóm kỹ thuật, điều này có nghĩa là họ sẽ dành ít thời gian hơn để tìm kiếm trong các tài liệu, trò chuyện và phiếu yêu cầu rải rác, và có nhiều thời gian hơn để lưu giữ các quyết định mà những công cụ đó thường che lấp.
Nếu vấn đề của bạn là “tài liệu của chúng tôi về mặt kỹ thuật đã hoàn thành, nhưng không ai tìm thấy chúng”, đó là vấn đề về khả năng tìm kiếm. Một không gian làm việc kết nối có thể giúp giải quyết điều này.
Nếu vấn đề của bạn là “tài liệu tham khảo API của chúng tôi đã lỗi thời”, đó là vấn đề liên quan đến công cụ tạo và kiểm duyệt. Sphinx, Javadoc, JSDoc hoặc Godoc sẽ hữu ích hơn so với một công cụ trong không gian làm việc. Đừng nhầm lẫn giữa hai khái niệm này.
Điều gì sẽ thay đổi khi AI viết phần lớn tài liệu?
Có một câu đùa thường được nhắc đến trên các chủ đề r/developersIndia, r/webdev và r/AskProgramming về tài liệu kỹ thuật. Khi ai đó hỏi nhóm xử lý tài liệu như thế nào, câu trả lời phổ biến nhất thường là một phiên bản của: “Tôi chính là tài liệu.”
Điều đó thật buồn cười vì nó đúng. Trong nhiều năm qua, giải pháp tạm thời cho việc thiếu tài liệu chính là những kỹ sư tình cờ còn nhớ.
AI thay đổi tiêu chuẩn cơ bản. Nó có thể soạn thảo tài liệu thường quy một cách nhanh chóng, khiến cho những quyết định không được ghi chép trở nên khó bào chữa hơn. Khi AI có thể xây dựng phần cơ bản của tài liệu trong vài giây, câu nói “tôi sẽ nhớ thôi” không còn được chấp nhận như một hệ thống lưu trữ chính thức nữa.
Điều này chuyển trọng tâm công việc của kỹ sư sang ý định, quyết định và sự đánh đổi: những phần mà cú pháp đơn thuần không thể giải thích được.
Phần lớn các lời khuyên về tài liệu trước đây được viết cho quy trình làm việc trước thời đại AI. Chúng tập trung chủ yếu vào mô tả tham số, chữ ký hàm và các ghi chú thiết lập chi tiết.
AI hiện nay có thể soạn thảo phần lớn công việc đó. Nếu các kỹ sư dành phần lớn thời gian lập tài liệu cho các bản tóm tắt máy móc, họ đang dành sự chú ý của con người cho tầng có giá trị thấp nhất.
Hãy dành thời gian đó để ghi chú về ý định: lý do tại sao hàm này tồn tại, tùy chọn nào bạn đã loại bỏ, và giả định nào mà mã nguồn phụ thuộc vào. Đó chính là những ghi chú mà nhóm tương lai của bạn, các tác nhân lập trình AI, và kỹ sư sẽ tiếp quản mã nguồn vào năm 2027 sẽ cần đến.
Nếu vấn đề tài liệu của bạn là bối cảnh bị phân tán, ClickUp có thể giúp lưu giữ lịch sử quyết định gần hơn với các công việc, tài liệu và dự án đã tạo ra chúng.
Câu hỏi thường gặp về tài liệu mã
README là gì?
Một tệp README vượt qua bài kiểm tra đầu tiên khi người đóng góp có thể nhanh chóng tìm thấy năm điều sau: dự án làm gì, cách thiết lập, cách sử dụng, cách đóng góp và nơi tìm kiếm trợ giúp. Nếu phần thiết lập bị chôn vùi dưới các huy hiệu, ghi chú về kiến trúc hoặc chi tiết nhật ký thay đổi, thì tệp README đó được sắp xếp không hợp lý.
Sự khác biệt giữa bình luận mã nguồn và tài liệu là gì?
Các bình luận mã nằm trong các tệp nguồn và giải thích các dòng hoặc khối mã cụ thể. Tài liệu thường nằm bên ngoài các tệp nguồn trong các tệp README, wiki, trang tham khảo được tạo tự động hoặc tài liệu API. Bình luận giúp nhà phát triển tiếp theo hiểu hàm của bạn. Tài liệu giúp người tiếp theo cố gắng sử dụng, chạy hoặc đóng góp cho dự án của bạn.
Lớp Ý định trong tài liệu mã là gì?
Lớp Ý định là phần của tài liệu mã nguồn ghi lại lý do tại sao mã nguồn tồn tại, chứ không phải nó làm gì: quyết định đã được đưa ra, sự đánh đổi đã chấp nhận, ràng buộc đã định hướng thiết kế và các phương án mà nhóm đã từ chối. Mã nguồn thể hiện hành vi; Lớp Ý định lưu giữ lý do. Các công cụ AI như GitHub Copilot và Mintlify có thể soạn thảo Lớp Cơ học (loại tham số, tóm tắt hàm) nhưng không thể suy ra Lớp Ý định từ cú pháp. Nó thường tồn tại trong Bản ghi Quyết định Kiến trúc, mô tả PR hoặc các bình luận giải thích tại sao thay vì làm gì.
Tài liệu mã nên được cập nhật bao lâu một lần?
Cập nhật tài liệu trong cùng một yêu cầu Hợp nhất thay đổi hành vi cơ bản. Nếu chữ ký hàm thay đổi, chuỗi tài liệu (docstring) cũng sẽ thay đổi trong yêu cầu Hợp nhất đó. Đối với các tệp README và tài liệu kiến trúc, hãy kiểm tra ít nhất một lần mỗi bản phát hành hoặc hàng quý. Tài liệu lỗi thời rất nguy hiểm vì nó hướng dẫn người đọc về hành vi, API hoặc quy trình sai.
Có bao nhiêu loại tài liệu?
Khung Diátaxis được áp dụng rộng rãi chia tài liệu thành bốn loại: hướng dẫn (hướng đến việc học, dành cho người mới bắt đầu), hướng dẫn thực hành (hướng đến công việc, dành cho người dùng giải quyết một vấn đề cụ thể), tài liệu tham khảo (hướng đến thông tin, dành cho người dùng tra cứu chi tiết) và giải thích (hướng đến sự hiểu biết, dành cho người dùng muốn biết bối cảnh). Việc trộn lẫn các loại này sẽ tạo ra tài liệu mà không ai có thể sử dụng được. Một tệp README cố gắng trở thành một hướng dẫn đầy đủ có thể che lấp đường dẫn thiết lập. Một trang tham khảo được viết như một bài luận có thể che giấu lệnh gọi API.
Việc cần làm để ghi chép mã bằng AI là gì?
Sử dụng AI cho lớp cơ học và tự viết lớp ý định. Các công cụ như GitHub Copilot, Cursor và Mintlify có thể soạn thảo các chuỗi tài liệu, mô tả tham số, giá trị trả về và tóm tắt hàm trực tiếp trong trình chỉnh sửa của bạn. Xem lại bản nháp so với hành vi thực tế của mã, sau đó thêm các phần mà AI không thể suy luận: lý do quyết định, ràng buộc dẫn đến quyết định đó, lựa chọn bạn đã từ chối và bất kỳ giả định nào mà mã phụ thuộc vào. Đối với các quyết định cấp hệ thống, hãy viết Bản ghi quyết định kiến trúc. Không bao giờ công bố tài liệu do AI tạo ra mà không có sự kiểm duyệt của con người.
Tài liệu do AI tạo ra có đáng tin cậy không?
Tài liệu do AI tạo ra rất hữu ích cho các công việc cơ bản như mô tả tham số, giá trị trả về và tóm tắt hàm cơ bản, nhưng vẫn cần sự kiểm duyệt của con người. Các công cụ như GitHub Copilot, Cursor, Codeium và Mintlify xử lý tốt những công việc này. AI không thể suy luận lý do tại sao một sự đánh đổi được thực hiện, những phương án thay thế nào đã bị loại bỏ, hoặc những hạn chế về sản phẩm, kinh doanh hay cơ sở hạ tầng nào đã định hình thiết kế. Hãy sử dụng AI để soạn thảo bản nháp đầu tiên. Sau đó, tự mình bổ sung ý định và bối cảnh.
Mỗi hàm có cần một docstring không?
Không. Các API công khai và bất kỳ hàm nào mà nhà phát triển khác sẽ gọi đều cần docstrings. Các hàm trợ giúp riêng tư được sử dụng trong một tệp thường không cần, trừ khi logic của chúng không rõ ràng. Việc tài liệu hóa quá mức đối với mã đơn giản sẽ tạo ra gánh nặng bảo trì mà không mang lại sự rõ ràng. Hãy điều chỉnh mức độ chi tiết của tài liệu sao cho phù hợp với đối tượng sử dụng của hàm.
Công cụ nào là tốt nhất để tạo tài liệu về mã?
Công cụ phù hợp phụ thuộc vào ngôn ngữ lập trình của bạn. Các nhóm Java sử dụng Javadoc, các nhóm JavaScript và TypeScript sử dụng JSDoc, các nhóm Python sử dụng Sphinx, các nhóm Go sử dụng Godoc, và Doxygen hỗ trợ C, C++ và một số ngôn ngữ khác. Các công cụ được hỗ trợ bởi AI như Mintlify, Swimm, Copilot và Cursor có thể giúp soạn thảo hoặc duy trì tài liệu trong các giai đoạn khác nhau của quy trình làm việc, nhưng chúng không thể thay thế các công cụ tạo tài liệu gốc của ngôn ngữ.
Một tệp README nên dài bao nhiêu?
Đủ dài để trả lời nhanh các câu hỏi cơ bản: dự án làm gì, cách cài đặt, cách sử dụng, cách đóng góp và nơi tìm kiếm trợ giúp. Đặt các chi tiết sâu hơn về thiết lập, kiến trúc và API vào các tài liệu được liên kết hoặc các thư mục con.