Lợi nhuận:
- Khả năng tạo bản nháp README, chuỗi tài liệu và nhật ký thay đổi dựa trên đối tượng và nguồn mục tiêu bằng AI
- Khả năng tách các lớp 'cái gì/như thế nào' và 'tại sao' trong tài liệu và thêm 'tại sao' với tư cách là con người
- Xác minh các bước cài đặt bằng cách đích thân chạy chúng và biến tài liệu thành một phần của quá trình thay đổi mã
Phần thường bị bỏ qua nhất nhưng tồn tại lâu nhất của phần mềm là tài liệu. Mã có thể đọc được ngay cả sau nhiều tháng; Người viết nó đã biến mất, bối cảnh bị lãng quên, chỉ còn lại những gì được viết ra. Một README tốt (tài liệu giới thiệu giải thích dự án là gì cũng như cách cài đặt và chạy nó), nhận xét mã giải thích và tài liệu API cập nhật (tài liệu tham khảo giải thích cách sử dụng giao diện) sẽ trực tiếp xác định tốc độ của một nhóm. AI loại bỏ rất nhiều “sự mệt mỏi khi viết” khỏi tài liệu - nhưng nó có một cái bẫy: AI có thể suy ra chức năng của nó từ mã, nhưng thường không thể biết tại sao nó lại làm như vậy.
Trong phần này, bạn sẽ tìm hiểu cách tạo README, nhận xét mã, chuỗi tài liệu (khối nhận xét được viết cho mỗi hàm/lớp), tài liệu API và nhật ký thay đổi bằng AI; và cách bảo tồn một cách nhân đạo phần tài liệu có giá trị nhất: câu hỏi “tại sao”.
Phân biệt giữa “Cái gì” và “Tại sao”
Có hai lớp tài liệu. Đầu tiên là cái gì/làm thế nào: "chức năng này sắp xếp danh sách", "chạy lệnh này để cài đặt". Chúng có thể được trích xuất từ mã và cấu trúc; AI vượt trội ở đây. Thứ hai, tại sao: "tại sao chúng tôi làm cho dịch vụ này không đồng bộ thay vì đồng bộ", "tại sao giá trị giới hạn này là 30 giây", "tại sao chúng tôi chọn thư viện này thay vì thư viện kia". Chúng không được viết bằng mã; Nó là sản phẩm của những quyết định thiết kế, những ràng buộc và nỗi đau trong quá khứ.
AI không biết “tại sao”; Tốt nhất, nó chỉ đưa ra một phỏng đoán hợp lý – điều này rất nguy hiểm, bởi vì một lý do sai còn tệ hơn là không có lý do nào cả. Vì vậy, sự phân công lao động rất rõ ràng: AI soạn thảo câu hỏi “cái gì/như thế nào”, bạn thêm câu hỏi “tại sao”. Nhận xét có giá trị nhất là nhận xét nói lên điều mà mã không thể nói.
Mẹo: Đừng lặp lại nhận xét về nội dung rõ ràng của mã (chẳng hạn như i = i + 1 // tăng i lên một). AI đôi khi đưa ra những bình luận dư thừa như vậy; Hãy loại bỏ chúng và dành năng lượng của bạn cho những nhận xét “tại sao”.
Từng bước: Tạo tài liệu bằng AI
- Chỉ định đối tượng mục tiêu. “Một nhà phát triển mới bắt đầu”, “nhóm bên ngoài sẽ sử dụng API này”, “tôi trong tương lai” - khán giả quyết định ngôn ngữ và chiều sâu.
- Cho nguồn đi. Thêm mã liên quan, README hiện có, ví dụ sử dụng vào lời nhắc. Một tài liệu không có nguồn gốc là một lời mời để bịa đặt.
- Cấu trúc áp đặt. Các phần tiêu chuẩn cho README (Mục đích, Cài đặt, Cách sử dụng, Cấu hình, Đóng góp), định dạng dự án cho chuỗi tài liệu.
- Đánh dấu các khoảng trống "tại sao". Yêu cầu AI đánh dấu các quyết định mà nó không biết lý do căn bản là "ở đây cần có ghi chú 'tại sao'"; Sau đó bạn điền vào những chỗ trống đó.
- Xác minh. Thực tế chạy các bước cài đặt; thử mã mẫu. Một README không hoạt động còn tệ hơn cả việc không có README.
Ba hộp nhỏ
Trường hợp 1 - README tăng tốc quá trình giới thiệu. README của một công cụ nguồn mở bị thiếu; Những người đóng góp mới phải vật lộn với quá trình cài đặt trung bình trong 2 giờ. Nhóm đã cung cấp các tập lệnh cài đặt và pack.json cho AI và soạn thảo một README có cấu trúc, sau đó tự chạy các bước trên một máy sạch và thêm hai phần phụ thuộc còn thiếu. Thời gian cài đặt cho những người đóng góp tiếp theo giảm xuống mức trung bình là 25 phút.
Trường hợp 2 - Cái bẫy “tại sao” bịa đặt. Một nhà phát triển đã yêu cầu AI đưa ra nhận xét bên cạnh giá trị thời gian chờ (timeout=30). AI đã viết lời biện minh hợp lý nhưng không chính xác "để chịu đựng độ trễ mạng cao"; lý do thực sự là giới hạn 30 giây theo hợp đồng của dịch vụ hạ nguồn. Việc hiểu sai đã khiến nhà phát triển tiếp theo tăng giá trị một cách không cần thiết, dẫn đến sự cố. Bài học: chủ sở hữu mã phải xác minh lý do biện minh.
Trường hợp 3 - Tiêu chuẩn Docstring đã được tự động hóa. Một mô-đun phụ trợ có 40 chức năng không có chuỗi tài liệu. AI đã được cung cấp định dạng dự án (kiểu Google) và tạo ra các mô tả tham số, trả về và ngoại lệ cho từng chức năng; Nhà phát triển đã xem xét những điều này và sửa một số khai báo kiểu không chính xác. Việc ghi lại 40 chức năng đã giảm từ khoảng nửa ngày xuống còn một giờ.
Bốn mẫu có thể sao chép
Dự thảo README có cấu trúc:
Đối tượng mục tiêu: {{e.g. người đóng góp mới}}.Viết bản nháp README dựa trên các tệp bên dưới. Các phần: Mục đích, Tính năng, Yêu cầu, Cài đặt, Vận hành, Cấu hình, Kiểm tra, Đóng góp. Trích xuất các lệnh cài đặt/chạy từ các tệp thực tế; PHÙ HỢP. Đánh dấu những chỗ bạn không chắc chắn bằng "[VERIFY]". Nguồn: {{package.json / scripts / mã mẫu}}
Tham chiếu chuỗi tài liệu/API:
Viết chuỗi tài liệu cho các hàm này theo định dạng {{project style: Google/NumPy/JSDoc}}: tóm tắt ngắn, tham số (loại + ý nghĩa), trả về, đưa ra ngoại lệ, 1 ví dụ ngắn. Đừng lặp lại những gì mã nói RÕ RÀNG. Đánh dấu các quyết định thiết kế yêu cầu "tại sao" là "[TẠI SAO CẦN THIẾT]", không viết lời giải thích bịa đặt.{{code}}
Xóa khoảng trắng cho nhận xét "tại sao":
Trong mã này, nhà phát triển tiếp theo có thể hỏi "tại sao lại như vậy?" (những con số kỳ diệu, những quyết định bất thường, cách giải quyết). Đưa ra nhận xét SKELETON cho mỗi mục, nhưng để trống phần lý do; Tôi sẽ đưa ra lời giải thích.{{code}}
Tuyên bố về nhật ký thay đổi/PR:
Viết một {{mục nhập thay đổi / mô tả PR}} từ điểm khác biệt bên dưới. Định dạng: Điều gì đã thay đổi (bằng ngôn ngữ người dùng), Tại sao (vấn đề: {{...}}), Thay đổi lớn (nếu có), Đã được thử nghiệm chưa. Điều chỉnh thuật ngữ kỹ thuật cho phù hợp với đối tượng mục tiêu.{{diff}}
Dấu nhắc yếu / Dấu nhắc mạnh
Yếu: "Viết README cho dự án này."
Mạnh: "Đối tượng mục tiêu: nhà phát triển nhân bản kho lưu trữ này lần đầu tiên. Dựa trên gói.json, docker-compose.yml và scripts/ thư mục đính kèm, hãy viết bản nháp README với các phần Mục đích, Yêu cầu, Cài đặt, Vận hành, Kiểm tra, Đóng góp. Trích xuất các lệnh từ các tệp này, không tạo ra chúng; đánh dấu bất kỳ chỗ nào bạn không chắc chắn bằng [XÁC MINH]."
Phiên bản mạnh mẽ mang đến cho khán giả, nguồn, cấu trúc và quy tắc “làm, đánh dấu”; để tài liệu dựa trên hồ sơ thật và những chỗ cần xác minh được hiển thị rõ ràng.
Loại tài liệu
AI làm tốt
Con người thêm/xác minh
Cài đặt README
bước phác thảo
Chạy các bước và xác nhận
Chuỗi tài liệu/API
Cấu trúc, thông số, loại
Đúng loại và "tại sao"
Nhận xét mã
Tóm tắt "Anh ấy đang làm gì"
Lời biện minh "Tại sao thế này"
Nhật ký thay đổi/PR
bản thảo đầu tiên
Tác động và độ chính xác
Quyết định kiến trúc (ADR)
bộ xương
Những quyết định và thỏa hiệp thực sự
Tài liệu yêu cầu bảo trì
Khía cạnh nguy hiểm nhất của một tài liệu là khi nó có vẻ đúng mặc dù nó sai. Khi mã thay đổi và tài liệu không được cập nhật, nó sẽ chủ động đánh lừa người đọc. AI giúp việc cập nhật trở nên dễ dàng: đưa ra một điểm khác biệt và hỏi “sự thay đổi này ảnh hưởng đến phần nào của tài liệu?” bạn có thể hỏi. Nhưng đó là quy trình đảm bảo tính cập nhật - làm cho phần cập nhật tài liệu trở thành một phần của thay đổi mã (tiêu chí chấp nhận của PR). AI tăng tốc; Nhóm xây dựng kỷ luật.
Thận trọng: Không xuất bản mà không xác minh các bước cài đặt trong README. Một tài liệu "có thể sẽ hiệu quả" có thể hủy hoại ngày làm việc đầu tiên của nhà phát triển mới và làm xói mòn lòng tin. Tự mình thực hiện các bước trong môi trường sạch sẽ.
Những lỗi thường gặp
- Tìm “lý do” để phù hợp với AI. Lời biện minh sai lầm còn tệ hơn là không có lời biện minh nào; Chủ mã nên viết lý do thiết kế.
- Không xác minh các bước cài đặt. README không hoạt động sẽ phá hủy niềm tin.
- Bình luận không cần thiết lặp lại mã. Nó tạo ra tiếng ồn, che khuất những diễn giải thực sự về "tại sao".
- Không xác định đối tượng mục tiêu. Một tài liệu không rõ ràng được viết cho ai sẽ không có ích gì cho người mới hoặc chuyên gia.
- Tách bản cập nhật khỏi quy trình. Nếu tài liệu không được cập nhật mã, nó sẽ nhanh chóng trở nên sai lệch.
Tóm lại
AI loại bỏ phần lớn gánh nặng cơ học khỏi tài liệu: bản nháp nhanh README, chuỗi tài liệu, tham chiếu API, nhật ký thay đổi và mô tả PR. Nhưng nó không thể biết được “tại sao”, đó là lớp có giá trị nhất, nếu bịa ra sẽ rất nguy hiểm. Sự phân công lao động rất rõ ràng: AI tạo ra câu hỏi “cái gì/như thế nào”, bạn thêm câu hỏi “tại sao”. Chỉ định đối tượng, cung cấp tài nguyên, áp đặt cấu trúc, đánh dấu các vị trí phù hợp và xác minh từng bước cài đặt bằng cách tự chạy nó. Biến tài liệu thành một phần không thể thiếu trong quá trình thay đổi mã.
Nhiệm vụ ứng dụng
Chọn một mô-đun hoặc dự án nhỏ có tài liệu bị thiếu hoặc lỗi thời. Trước tiên, hãy tạo một bản phác thảo từ AI bằng mẫu “bản nháp README có cấu trúc” (hoặc chuỗi tài liệu); Hãy chắc chắn để cung cấp nguồn và đối tượng mục tiêu. Sau đó đi qua từng điểm mà AI đã đánh dấu [XÁC MINH] hoặc [TẠI SAO CẦN]: thực tế chạy các bước thiết lập và điền vào phần “tại sao” thiết kế bằng kiến thức của riêng bạn. Lưu ý có bao nhiêu bước cần phải sửa và bạn đã thêm bao nhiêu câu hỏi “tại sao”.
danh sách kiểm tra
- [ ] Trong tài liệu, tôi phân biệt các lớp "cái gì/như thế nào" và "tại sao".
- [ ] Tôi không bắt AI bịa ra câu "tại sao", tôi tự thêm vào.
- [ ] Tôi đưa ra lời nhắc đối tượng mục tiêu và các tệp nguồn thực tế.
- [ ] Tôi xác minh các điểm [XÁC MINH] được AI đánh dấu bằng cách đích thân thực hiện chúng.
- [ ] Tôi loại bỏ những nhận xét không cần thiết lặp lại mã.
- [ ] Tôi đang thực hiện một phần cập nhật tài liệu của quá trình thay đổi mã.