Làm thế nào để ghi lại một trang web nhỏ hiện có (ứng dụng web), trong và ngoài?

Question

Chúng tôi có một "ứng dụng web" đã được phát triển trong 7 tháng qua. Vấn đề là, nó không thực sự được ghi nhận. Các yêu cầu bao gồm một danh sách nhỏ có dấu đầu dòng từ cuộc họp ban đầu 7 tháng trước (đó là một tuyên bố "mục tiêu" nhiều hơn các yêu cầu phần mềm). Nó đã thu thập một số tính năng bắt nguồn từ các cuộc thảo luận bằng lời nói hoặc trò chuyện nhỏ.

Nhà phát triển sắp ra mắt. Anh ấy đã viết toàn bộ bản thân mình và anh ấy biết tất cả những điều kỳ quặc và quy tắc cơ bản cho mỗi trang, nhưng không ai khác thực sự biết nhiều hơn giao diện người dùng của nó; điều này tất nhiên là phần dễ dàng, vì nó được thực hiện trực quan với người dùng. Nhưng nếu ai đó cần phải sửa chữa hoặc thêm một tính năng vào nó, toàn bộ điều là một hộp đen. Mã có một số ý kiến ​​tối thiểu, và tất nhiên điều tốt về các ứng dụng web là thanh địa chỉ chỉ cho bạn đúng hướng để sửa chữa một vấn đề hoặc nâng cấp một trang.

Nhưng nhà phát triển nên làm cách nào để ghi lại ứng dụng web này? Anh ta bị mất một chút khi bắt đầu. Là nhà phát triển, làm thế nào để bạn hoàn toàn làm tài liệu cho các ứng dụng web của mình cho các nhà phát triển, người duy trì và người dùng cấp quản trị khác? Bạn sử dụng phương pháp nào, bạn bắt đầu từ đâu, phần mềm nào bạn sử dụng, bạn có mẫu không?

Ý tưởng về độ lớn: nó sử dụng PHP, MySQL và jQuery. Nó có khoảng 20-30 tệp chính (giao diện người dùng), cùng với khoảng 15 tệp được bao gồm và một vài thư mục của một số nội dung - vì vậy tổng thể đó là một ứng dụng khá nhỏ. Nó giao tiếp với 7 bảng MySQL, mỗi bảng được đặt tên tốt, vì vậy tôi nghĩ rằng kết thúc cơ sở dữ liệu khá tự giải thích. Có một tệp config.inc.php với các định nghĩa về các const giống như chi tiết người dùng MySQL, một số từ/tới email và URL mà PHP sử dụng để chèn vào email và trang (đường dẫn tương đối và tuyệt đối, cơ sở). Có một số AJAX thông qua jQuery.

hãy góp ý, nếu có bất kỳ thông tin nào khác mà có thể giúp bạn giúp tôi và tôi sẽ được vui để chỉnh sửa nó trong.

---

Nhà phát triển lá vào thứ Sáu. Tuy nhiên, ông có thể dành hầu hết 24 giờ còn lại của mình cho nhiệm vụ tài liệu này. Vì vậy, yeah, mọi thứ đang ảm đạm nhưng 24 giờ là khá một chút ... phải không? : - \

Answer 1

Tôi sẽ bắt đầu bằng cách liệt kê các tính năng chính mà ứng dụng hiện đang thực hiện (cập nhật điểm bullet ban đầu).

Sau đó, đối với mỗi dấu đầu dòng, hãy viết ra các yêu cầu chính liên quan đến điểm dấu đầu dòng đó.

Đối với mỗi yêu cầu, hãy viết ra:

• Bất cứ điều gì kỳ quặc về điều đó yêu cầu đặc biệt
• ở đâu trong đoạn code đó yêu cầu được thực hiện (mà php, file inc, bảng)

này sẽ cung cấp cho bạn thứ gì đó của hệ thống phân cấp truy vết

Tính năng => Yêu cầu => Triển khai

Nó cũng sẽ cung cấp một khuôn khổ tốt để jostle kỷ niệm và viết xuống của gotcha.

Sau đó, hãy nhận xét từng trang php và trang.

Bắt đầu với tiêu đề nêu rõ mục đích và (các) yêu cầu nào từ danh sách trước được đáp ứng (truy xuất ngược từ mã này đến yêu cầu).

Đi qua từng tệp php/inc và nhận xét các hành động/quyết định/vòng chính cho biết những gì họ đang cố gắng thực hiện và bất kỳ cân nhắc thiết kế nào được giả định (ví dụ: "đầu vào được giả định đã được xác thực trong bước trước") .

Khi nhận xét mã nguồn, bạn có thể muốn sử dụng công cụ như PHPDoc để bạn có thể tạo tài liệu từ các nhận xét.

Answer 2

Một cách tiếp cận có thể là sắp xếp một loạt các cuộc họp bàn giao. Trong các nhà phát triển này sẽ phải giải thích mã cho từng phần.

Anh ấy có thể viết một số ghi chú để chuẩn bị cho chúng, nhưng việc để các nhà phát triển khác mất vài phút cũng có thể giúp họ hiểu mã. Các cuộc họp này cũng sẽ là cơ hội để đặt câu hỏi về các khía cạnh không rõ ràng.

Đừng cố gắng thực hiện toàn bộ trang web trong một lần. Chia nhỏ nó thành hai phần nhỏ hơn bằng cách nào đó - theo chức năng hoặc theo khu vực. Điều này có nghĩa là các nhà phát triển khác của bạn không bị ném bom với quá nhiều thông tin trong một lần, nhà phát triển ban đầu có thể tập trung vào một khu vực đúng lúc và bạn có cơ hội theo dõi sau cuộc họp.

Ngay cả khi không có gì "dính" ngay lập tức, sẽ có một số điểm quen thuộc với trang web khi bạn truy cập lại trang sau.

Một cách tiếp cận khác có thể là để nhà phát triển đưa ra một loạt các bản trình bày ngắn trên trang web và cách nó được xây dựng. Điều này có thể nhắc anh nhớ lại lý do tại sao anh lại thực hiện các phương pháp mà anh đã làm. Điều này là vô giá khi nhìn vào mã. Nếu bạn biết vấn đề gì mà nó đang cố giải quyết thì sẽ dễ hiểu hơn nhiều.