Phương pháp để ghi lại cơ sở mã hiện có

Tôi làm việc như một phần của một nhóm trên một ứng dụng hiện có không có tài liệu nội tuyến, cũng không có tài liệu kỹ thuật. Khi tôi đang làm việc với các báo cáo lỗi khác nhau trên ứng dụng, tôi đã tự viết một loại dấu vết bánh mì - số lỗi ở nhiều nơi để nhà phát triển tiếp theo có thể tham khảo số lỗi đó để xem điều gì đang xảy ra.

Câu hỏi của tôi là như vậy:

Phương pháp hiệu quả nhất để ghi lại mã này là gì? Tôi có nên ghi lại tài liệu khi tôi chạm vào khu vực (phương pháp vi-rút, nếu bạn muốn) hoặc tôi nên tự mình ghi lại từng phần và không theo các đường dẫn đi ra các khu vực khác của ứng dụng? Tôi có nên chèn các bình luận nội tuyến không tồn tại trước đây không (với nỗi sợ rằng cuối cùng tôi có thể xác định không chính xác những gì mã làm)?

Phương pháp nào bạn sẽ sử dụng để ghi lại chính xác và nhanh chóng một ứng dụng khá lớn không có tài liệu nội tuyến hiện có, cũng như các tài liệu tham khảo nội tuyến cho tài liệu bên ngoài?

Tài liệu mã cơ sở

Tôi đặc biệt khuyên bạn nên tuân theo quy tắc trinh sát với các cơ sở mã kế thừa. Cố gắng ghi lại một dự án cũ một cách độc lập để làm việc với nó sẽ không bao giờ xảy ra.

Tài liệu trong mã

Điều quan trọng nhất là sử dụng các phương tiện tài liệu trong môi trường phát triển đã chọn của bạn, điều đó có nghĩa là pydoc cho python, javadoc trong các bình luận java hoặc xml trong C #. Điều này làm cho nó dễ dàng để viết tài liệu cùng lúc với việc viết mã.

Nếu bạn dựa vào việc quay lại và ghi lại những điều sau đó, bạn có thể không nhận được nó, nhưng nếu bạn làm điều đó khi bạn đang viết mã, thì những gì cần được ghi lại sẽ rất mới mẻ trong tâm trí bạn. C # thậm chí có tùy chọn đưa ra cảnh báo biên dịch nếu tài liệu XML không đầy đủ hoặc không phù hợp với mã thực tế.

Các xét nghiệm như tài liệu

Một khía cạnh quan trọng khác là có tích hợp tốt và kiểm tra đơn vị.

Thông thường tài liệu tập trung vào những gì các lớp và phương thức thực hiện một cách cô lập, bỏ qua cách chúng được sử dụng cùng nhau để giải quyết vấn đề của bạn. Các thử nghiệm thường đặt chúng vào bối cảnh bằng cách hiển thị cách chúng tương tác với nhau.

Tương tự, các bài kiểm tra đơn vị thường chỉ ra các phụ thuộc bên ngoài một cách rõ ràng thông qua đó mọi thứ cần được Mock ed out.

Tôi cũng thấy rằng sử dụng phần mềm phát triển dựa trên thử nghiệm, tôi viết phần mềm dễ sử dụng hơn, bởi vì tôi đang sử dụng nó ngay từ đầu. Với một khung kiểm thử tốt, làm cho mã dễ kiểm tra hơn và làm cho nó dễ sử dụng thường là điều tương tự.

Tài liệu cấp cao hơn

Cuối cùng, có những gì để làm về cấp độ hệ thống và tài liệu kiến ​​trúc. Nhiều người sẽ ủng hộ việc viết tài liệu đó trong wiki hoặc sử dụng Word hoặc trình xử lý văn bản khác, nhưng đối với tôi, nơi tốt nhất cho tài liệu đó cũng bên cạnh mã, trong một định dạng văn bản đơn giản, thân thiện với hệ thống kiểm soát phiên bản.

Giống như với tài liệu trong mã, nếu bạn lưu trữ tài liệu cấp cao hơn trong kho lưu trữ mã của mình thì bạn có nhiều khả năng sẽ cập nhật nó. Bạn cũng nhận được lợi ích là khi bạn rút phiên bản XY của mã, bạn cũng nhận được phiên bản XY của tài liệu. Ngoài ra, nếu bạn sử dụng định dạng thân thiện với VCS, điều đó có nghĩa là nó dễ dàng phân nhánh, tìm khác biệt và hợp nhất, giống như mã của bạn.

Tôi khá thích đầu tiên , vì nó dễ dàng tạo ra cả trang html và tài liệu pdf từ nó, và thân thiện hơn LaTeX , nhưng vẫn có thể bao gồm các biểu thức toán học LaTeX khi bạn cần chúng.

Câu hỏi khó. Về cơ bản, tôi sẽ sử dụng phương pháp "tái cấu trúc", mà tôi sẽ gọi là "nếu bạn chạm vào mã, ghi lại nó".

Nhưng phải chính xác; khi các vấn đề xuất hiện và khi bạn phải làm quen với mã để sửa các lỗi xảy ra, tôi nói rằng bạn nên sử dụng sự quen thuộc đó để viết bình luận về mã đó nói riêng; về bản chất, động lực để sửa lỗi tại thời điểm đó đã buộc bạn phải làm quen đủ với mã để có thể ghi lại nó. Và vì lý do đó, tôi sẽ không theo dõi các nhánh không liên quan HOẶC ghi lại các hàm không liên quan, bởi vì tại thời điểm đó, nếu bạn không thực hiện kiểm tra mã chủ động (để xác minh sửa lỗi của mình), thì thật khó để hoàn toàn chắc chắn rằng bạn hiểu chính xác những gì mã làm và tại sao. (Tôi không gặp phải vấn đề rằng cũng khó có thể tìm ra chính xác điều gì và tại sao mã lại làm những gì ngay cả khi kiểm tra sửa lỗi; bạn '

Cách tiếp cận này có xu hướng tối đa hóa độ chính xác, với sự hy sinh tốc độ tổng thể, nhưng không ảnh hưởng đến nhu cầu của bạn để duy trì mã quá nghiêm trọng cùng một lúc. Tất nhiên, nếu nhiệm vụ sửa lỗi của bạn là nhỏ, bạn có thể mạo hiểm vào "lãnh thổ không xác định" và bắt đầu viết tài liệu ở đó, nhưng nếu bạn (như hầu hết chúng ta) không thể tìm đủ thời gian trong ngày để sửa mã và ghi lại tài liệu, thì điều này là một sự thỏa hiệp tốt

Một điều đáng chú ý là tốt; bạn nên có tài liệu bên ngoài tốt. Bạn nói rằng mã của bạn không có tài liệu tham khảo đến tài liệu bên ngoài; Tôi hy vọng cho lợi ích của bạn rằng tài liệu bên ngoài như vậy tồn tại, mặc dù. Nếu không, tôi thực sự sẽ viết tài liệu bên ngoài đó là ưu tiên hàng đầu của bạn; một cái gì đó ở cấp độ của một đặc tả chức năng là, tôi nghĩ, hoàn toàn quan trọng đối với tất cả các dự án phần mềm lớn. Lý do là các thông số chức năng, hoặc tài liệu cấp cao của biểu mẫu đó, có thể giúp ngăn chặn "tính năng leo" hoặc "trôi dạt tính năng" trong bất kỳ phần mềm nào; và tính năng trôi dạt (đặc biệt) có thể phá hủy tài liệu vì nó có thể khiến tài liệu trở nên lỗi thời. (Tôi xác định tính năng creep là sự bổ sung lũy ​​tiến (và gây khó chịu) cho một phần mềm; tính năng trôi dạtmặt khác, là nơi tập hợp các hành động mà phần mềm thực hiện thay đổi từ từ theo thời gian. Creep tính năng là THÊM, tức là nó thường liên quan đến việc tăng bộ chức năng của phần mềm; mặt khác, tính năng trôi là không tổng; Từng người một, một phần của chức năng cạnh được xác định để làm một cái gì đó khác nhau, cho đến khi phần mềm đang làm một cái gì đó hoàn toàn khác với dự định ban đầu. Tính năng trôi dạt là rất hiếm, nhưng CHẾT CHẾT cho tài liệu.)

Một ứng dụng mà tôi đồng phát triển trong suốt hai năm đã thiếu tài liệu nghiêm trọng. Tại một số điểm, rõ ràng là chúng tôi sẽ chuyển ứng dụng cho một nhà phát triển khác, người sẽ duy trì nó từ thời điểm đó trở đi, vì vậy chúng tôi phải ghi lại mã.

Để đối phó với phạm vi khổng lồ của quy trình tài liệu, tôi sẽ thử và ghi lại tất cả các mã trong một tính năng cụ thể hoặc một phần của ứng dụng vào một ngày nhất định. Tôi không có mô hình cụ thể, nhưng khăng khăng thực hiện một số việc mỗi ngày và có ý thức hoàn thành bằng cách ghi lại toàn bộ tệp hoặc phần của ứng dụng hàng ngày.

Phải mất nhiều tháng để ghi lại toàn bộ ứng dụng, nhưng trong nửa giờ (tối đa) một ngày, nó không bao giờ thực sự ăn vào lịch trình dự án và tránh được rất nhiều sự nhàm chán đi cùng với tài liệu.

Chúng tôi đã sử dụng tài liệu XML trong C # và nó cung cấp đủ các tính năng và cấu trúc để làm cho tài liệu trở nên dễ dàng. Ngay cả khi bạn không ghi lại một ứng dụng C #, mô hình có một bản tóm tắt ngắn trước tiên theo sau là các nhận xét là rất hữu ích.

Tôi sẽ tài liệu khi tôi thêm / sửa đổi mã. Ngoài ra, tôi cũng sẽ ghi lại các API công khai hoặc bất kỳ giao diện nào giữa các mô-đun. Nếu bạn đã ghi lại tất cả các mã, bạn có thể không thấy ROI cho thời gian sử dụng. Có thể hữu ích khi sử dụng một cái gì đó như wiki để tổ chức tài liệu bên ngoài khi bạn phát triển nó. Tài liệu hữu ích nhất mà tôi tham khảo khi tôi bắt đầu dự án cuối cùng của mình là tài liệu kiến ​​trúc. Nó bao gồm thông tin về các công nghệ được sử dụng và nó cung cấp một cái nhìn ở mức độ cao về cách ứng dụng được xếp lớp.

Tôi sẽ sử dụng ý kiến ​​Doxygen. Doxygen có nhiều định dạng đầu ra hơn hầu hết các định dạng miễn phí khác và rất dễ học.

Bạn thậm chí có thể xem xét việc thuê một nhà thầu để làm điều này, vì một số người trong chúng ta làm việc đó để kiếm sống. Tuy nhiên, với lựa chọn này, bạn vẫn phải cam kết xem xét các tài liệu.

Một kỹ thuật phổ biến khác là gán dev mới cho tài liệu mã. Sau đó, mỗi người mới đi qua nó khi họ tăng tốc. Xin lưu ý rằng một số nhà phát triển xem điều này như nhận được một kênh gốc - chỉ cần thiết trong các trường hợp trực tiếp, LOL.

Trước khi bạn bắt đầu viết tài liệu bất cứ điều gì, hãy phát triển một tiêu chuẩn. Điều này có thể đơn giản như đảm bảo rằng bạn viết một vài dòng trên tiêu đề hàm hoặc lớp thành một cái gì đó chính thức và dài dòng hơn (như javadoc). Trước khi bất cứ ai có thể kiểm tra mã, tài liệu của họ phải đáp ứng tiêu chuẩn đó.

Những gì tôi tìm thấy hoạt động tốt là thêm các nhận xét bằng văn bản trước tiêu đề chức năng cho các chức năng tôi đã tạo trước đây không có giấy tờ và thêm nhận xét nội tuyến vào bất cứ điều gì tôi đã thêm. Bạn muốn tránh mã tài liệu mà bạn chưa chạm vào. Thật tệ khi có những bình luận xấu hơn là không có bình luận nào và nếu bạn viết tài liệu này một cách 'nhanh chóng', có lẽ bạn sẽ viết bình luận xấu.