Làm thế nào để ghi lại một dự án đã được phát triển?

Tôi muốn biết những tùy chọn nào có sẵn để ghi lại một dự án đã được phát triển, vì các nhà phát triển đã làm việc không viết ngay cả một trang tài liệu.

Dự án không có chi tiết nào khác ngoài nhiều trang tập lệnh với các chức năng được viết và sửa đổi bởi các nhà phát triển đã làm việc cho dự án này từ 2 năm qua. Tất cả tôi có là lược đồ cơ sở dữ liệu và các tệp dự án. Tôi muốn biết liệu có cách nào để tổ chức dự án này và ghi lại nó để nó có thể hữu ích cho các nhà phát triển sẽ làm việc trong dự án này trong tương lai.

Dự án được phát triển với PHP và MySQL. Các chức năng được nhận xét kém vì vậy tôi không thể nhận được kết quả tốt khi tôi chạy nó với doxygen.

Ai sẽ đọc tài liệu? Tài liệu này sẽ được sử dụng để làm gì? Đây là những câu hỏi quan trọng nhất để trả lời. Ví dụ: tài liệu dành cho nhà phát triển bảo trì sẽ tập trung nhiều hơn vào cấu trúc trong khi tài liệu dành cho nhà phát triển tích hợp với sản phẩm sẽ tập trung nhiều hơn vào dịch vụ web và cấu trúc cơ sở dữ liệu.

Nói chung, làm nhiều tài liệu theo yêu cầu và không hơn. Nhiều tổ chức yêu cầu tài liệu vì ai đó khăng khăng đó là cách thực hành tốt nhất nhưng tài liệu cuối cùng lại thu thập bụi.

Giả sử rằng mọi người sẽ thực sự sử dụng tài liệu, đừng cố nắm bắt mã và cơ sở dữ liệu ở mức nhỏ nhất. Các nhà phát triển sẽ xem xét mã cho minutiae. Thay vào đó, hãy tập trung vào các chi tiết không rõ ràng trong mã , ví dụ:

1. Các trường hợp sử dụng sản phẩm đáp ứng. Điều này có thể khó khăn khi xem xét tuổi của sản phẩm nhưng việc nắm bắt ý nghĩa của sản phẩm sẽ mang lại bối cảnh quan trọng cho người đọc và người thử nghiệm phi kỹ thuật. Các đối thủ cạnh tranh trên thị trường (nếu có) là ai? Có bất cứ điều gì loại trừ khỏi phạm vi của sản phẩm?
2. Bất kỳ yêu cầu phi chức năng rõ ràng . Ví dụ, sản phẩm được viết để xử lý một khối lượng nhất định? Dữ liệu có thể bao nhiêu tuổi? Bộ nhớ đệm được sử dụng ở đâu? Người dùng được xác thực như thế nào? Kiểm soát truy cập hoạt động như thế nào?
3. Một sơ đồ ngữ cảnh hiển thị tương tác với các hệ thống khác, chẳng hạn như cơ sở dữ liệu, nguồn xác thực, sao lưu, giám sát, v.v.
4. (Nếu biết) Rủi ro và cách chúng được giảm nhẹ cùng với đăng ký quyết định . Điều này có lẽ khó khăn khi nhìn lại nhưng thường có những quyết định quan trọng ảnh hưởng đến một thiết kế. Nắm bắt bất cứ điều gì bạn biết.
5. Các mẫu thiết kế phổ biến hoặc hướng dẫn thiết kế . Ví dụ, có một cách tiêu chuẩn để truy cập cơ sở dữ liệu? Có một tiêu chuẩn mã hóa hoặc đặt tên?
6. Đường dẫn mã quan trọng , thường sử dụng biểu đồ luồng hoặc hoạt động UML hoặc sơ đồ trình tự. Có thể không có bất kỳ dự án nào nhưng đây thường là những người dùng doanh nghiệp đã khớp nối.

Ngay cả khi tất cả thông tin này không có sẵn, hãy bắt đầu ngay bây giờ . Các nhà phát triển đến sau bạn sẽ cảm ơn bạn.

Các bài kiểm tra đơn vị tự động tốt hoặc các trường hợp kiểm thử cũng có thể là tài liệu hữu ích, mặc dù khó truy cập cho những người ít kỹ thuật.

Có vẻ như bạn cần thực hiện một thay đổi văn hóa để bao gồm tài liệu . Bắt đầu nhỏ nhưng, lý tưởng nhất, dự án không nên được "thực hiện" cho đến khi nó có ít nhất một mức độ tài liệu tối thiểu. Đây có lẽ là bước khó nhất vì trên đây là những điều bạn có thể kiểm soát. Đây là thứ người khác phải mua vào. Tuy nhiên, nó cũng có thể là phần thưởng xứng đáng nhất, đặc biệt nếu dự án tiếp theo bạn làm đi kèm với tài liệu tốt.

Trước đây tôi đã quản lý một tình huống như thế này bằng cách ngồi xuống với các chủ sở hữu sản phẩm hoặc người sử dụng năng lượng khác nhau, trải qua các trường hợp sử dụng chính của họ và ghi lại những điều này bằng một loạt các thử nghiệm. Bạn có thể sử dụng chúng làm đường cơ sở cho hệ thống khi bạn bắt đầu thực hiện các thay đổi trong tương lai. Điều này cũng có thể giúp xác định các khu vực của hệ thống không có chủ sở hữu hoặc trường hợp sử dụng và có khả năng bị xóa.

Tất cả phụ thuộc vào kích thước của hệ thống thực sự. Nếu đây là một hệ thống phức tạp với nhiều bên liên quan khác nhau, bạn có thể tạo sơ đồ thành phần cấp cao nêu chi tiết những khả năng tồn tại và nơi chúng hài lòng. Điều này có thể rất hữu ích để xác định các vấn đề kiến ​​trúc trong thiết kế hệ thống.

Nói chung, tôi khuyên bạn nên tránh các tài liệu lỗi thời bởi vì nó sẽ bị lỗi thời và nó sẽ bỏ lỡ các nhà phát triển trong tương lai. Tôi luôn cố gắng tạo ra tài liệu sống dưới dạng các bài kiểm tra sẽ được duy trì khi hệ thống phát triển.

Điều đầu tiên trước tiên, đối tượng mục tiêu của bạn là ai? Nhà phát triển tương lai hay những người kinh doanh khác? Với câu trả lời cho câu hỏi đó trong đầu:

Như những người khác đã nói, một mô tả cấp cao là điều đầu tiên bạn cần. Giải thích những gì hệ thống đang cố gắng làm trong sơ đồ rộng hơn của mọi thứ. Giải thích những gì nó chạy trên, làm thế nào nó phù hợp với mạng và nói chuyện với bất kỳ hệ thống khác. Sau đó, tôi sẽ đi qua từng màn hình, chụp màn hình và đưa ra lời giải thích nhanh về những gì màn hình làm và cách nó tương tác với bất kỳ bộ phận nào khác của hệ thống. Nếu nó dành cho nhà phát triển, hãy giữ nó trò chuyện như bạn đang giải thích ứng dụng cho họ lần đầu tiên. Rốt cuộc, đó là điểm của tài liệu (tôi giả sử).

Bất kỳ xử lý hoặc logic phức tạp nào tôi đều sử dụng sơ đồ trạng thái, sơ đồ luồng dữ liệu hoặc sơ đồ tuần tự. Chắc chắn làm một sơ đồ thực thể, sau đó là một thiết kế lược đồ DB (hai thứ khác nhau!). Có thể một sơ đồ lớp cơ bản nhưng giữ cho nó đơn giản, chỉ lưu ý những thứ chính cần quan tâm, các nhà phát triển có thể tìm ra thứ đó bằng cách xem mã.

Nếu bạn gặp khó khăn khi bắt đầu, chỉ cần giả vờ có một nhà phát triển khác ở trong phòng ngay bên cạnh bạn, người không biết điều đầu tiên về hệ thống, tôi tương đối thiếu kiên nhẫn và chỉ cần biết ý chính của nó. Sau đó bắt đầu giải thích và viết ra những gì bạn nói :)

Các đề xuất trước đây đều là những gợi ý hay, nhưng tôi cũng sẽ xem xét nghiên cứu nếu cộng đồng người dùng của bạn tự tạo bất kỳ tài liệu quảng cáo nào. Câu hỏi của bạn không chỉ định liệu bất kỳ phiên bản nào của 'sản phẩm' của bạn (tồn tại trong hai năm) đã từng được phát hành cho người dùng hay chưa. Nếu nó đã được sử dụng và không có tài liệu chính thức, thì không có tài liệu nào là cần thiết, hoặc có một tài liệu 'không chính thức' nào đó có thể thô sơ, nhưng cũng có thể được người dùng coi là thiết yếu. Hãy thử tìm kiếm trên web các vật phẩm có khả năng đại diện cho các API quan trọng, diễn đàn tìm kiếm, hỏi người dùng quyền lực và tìm kiếm các trang web câu hỏi và trả lời. Nếu có thể, hãy cố gắng viết tài liệu đáp ứng nhu cầu kỹ thuật hoặc kinh doanh.

Câu hỏi là, bạn có muốn ghi lại nó như bây giờ hoặc như nó phải vậy không?

Những gì tôi đã đọc từ câu hỏi của bạn là bạn đang nghĩ về tài liệu API và không có quá nhiều tài liệu người dùng và mã có lẽ không được duy trì tốt và khó hiểu.

Tôi sợ nếu bạn làm tài liệu bây giờ, cuối cùng bạn sẽ vứt bỏ phần lớn công việc của mình, một khi mã được tái cấu trúc.

Tôi sẽ thực hiện theo cách tiếp cận sau:

• làm cho tài liệu không cần thiết càng nhiều càng tốt bằng cách tuân thủ các thực tiễn tốt nhất phổ biến. Chọn tên lớp tốt, tên phương thức, tên biến mà bạn có thể hiểu bằng trực giác
• phá vỡ các lớp quái vật khổng lồ và / hoặc các chức năng nơi nó có ý nghĩa
• sử dụng các bình luận PHPdoc - bạn có thể sử dụng các công cụ để tạo tài liệu API
• viết các bài kiểm tra cho nó: Các bài kiểm tra sẽ giúp bạn hiểu hoặc xác định những gì mã nên làm.

Bây giờ, bạn vẫn còn những thứ không có giấy tờ: đây có thể là khái niệm chung, kiến ​​trúc, v.v ... Đối với điều này, tôi thực sự sẽ viết tài liệu - nhưng chỉ viết những gì thực sự hữu ích và hữu ích.