Tài liệu xuống cấp - làm thế nào để đối phó với nó?

Quan trọng : chúng tôi không có vấn đề gì với tài liệu mã nguồn . Điều này thuộc về kiểm toán mã thường xuyên và được cập nhật. Vấn đề của chúng tôi là với tài liệu dành cho nhà phát triển (hoặc "bên ngoài" nếu bạn muốn), những mẹo nhỏ giống như blog từ lập trình viên đến lập trình viên có xu hướng được viết một lần, thường bị bỏ lại.

Chúng tôi sử dụng hệ thống giống như wiki để tạo tài liệu lập trình viên - các bài viết được viết bởi các lập trình viên cho các lập trình viên mô tả chi tiết hơn một chút về cách hoạt động của đoạn mã cụ thể. Những trang wiki thường bao gồm:

• động lực đằng sau các quyết định thiết kế cho các phần của API (ví dụ: chúng tôi đã làm điều xấu xí này vì thư viện bên thứ 3 đặc biệt này muốn mọi thứ được thực hiện theo cách này, vì thư viện khác này ..., vì ...)
• giải thích về cách chúng tôi xử lý các tác vụ phổ biến cụ thể (ví dụ: hiển thị cửa sổ bật lên tầm thường, cần tham chiếu các kiểu ứng dụng phù hợp, tự đăng ký trong thành phần đăng ký và triển khai một số giao diện để được tự động "quét" bởi thành phần khác)
• thực hành tốt (chủ quan là như vậy, chúng tôi thực sự viết những thứ này xuống)
• cấu hình môi trường, các công cụ cần thiết và thiết lập của nó

Nói chung, chủ yếu là những thứ liên quan đến viết mã không phù hợp với tài liệu mã thông thường do kích thước của nó và tính chất giống như bài viết / bài viết trên blog.

Vấn đề

Theo như giới thiệu hệ thống này có vẻ như là một ý tưởng tốt vài tháng trước, ngày nay tôi cảm thấy như nó gây ra nhiều vấn đề hơn nó giải quyết. Ví dụ:

• người làm ghi bài ... nhưng khi mã thay đổi, cập nhật wiki hiếm khi sau
• rất nhiều bài viết đầu , được viết bởi ai đó vội vàng và để lại như thế
• mặc dù yêu cầu bài viết thường xuất phát từ lãnh đạo dự án, nhưng hầu như không bao giờ được xác minh về tính chính xác / thành phần - đôi khi dẫn đến chất lượng kém

Sự xuống cấp thông thường. Mã thay đổi, wiki vẫn giữ nguyên. Lần tới khi ai đó tìm kiếm thông tin, những gì anh ta thường tìm thấy là một loạt những thứ lỗi thời, chất lượng thấp - và đang tự hỏi chuyện gì đang xảy ra, liệu những thứ anh ta tìm thấy là chính xác hay (thậm chí tệ hơn) những phần nào của nó. Và những gì được cho là để giúp đỡ, cuối cùng lại làm điều ngược lại.

Hiện tại có vẻ như mọi người nhận thức được vấn đề, bao gồm cả trưởng dự án, nhưng dường như không ai bận tâm làm bất cứ điều gì với nó (hoặc có nhiều thứ thú vị hơn để làm).

Suy nghĩ ban đầu của tôi là ném tất cả vào quên lãng (sau khi tôi bị cắn bởi những "mẹo" lỗi thời vài lần liên tiếp), nhưng tôi cho rằng điều đó có thể quá cực đoan. Một số thông tin đáng chú ý và đôi khi đọc tốt, nhưng vấn đề vẫn giống nhau: làm thế nào bạn đối phó với "tính kịp thời" của nó ? Có phải nó đã được liên kết với mã nguồn bằng cách nào đó (vì vậy khi kiểm tra phiên bản tệp cập nhật, tác giả của bài viết được thông báo rằng anh ta có thể cần phải sửa lại mã / bài viết)? Có người được chỉ định "xem qua" nó trên cơ bản hàng ngày? Dọn dẹp thường xuyên?

Có vẻ như bạn đang ghi lại quá nhiều thứ lặt vặt trong wiki.

Khối tài liệu của mã và phương thức trong mã . Cố gắng làm cho mã của bạn tự ghi lại tài liệu để bạn không phải đưa ra nhiều nhận xét. Viết bài kiểm tra đơn vị có thể giúp quá.

Các quyết định thiết kế tài liệu và kiến ​​trúc ở mức độ chi tiết cao hơn trong wiki vì vậy wiki không cần phải thay đổi thường xuyên hoặc mất nhiều công sức để thay đổi. Nếu nhiều người trong nhóm của bạn đã biết kiến ​​trúc và nhóm không phát triển nhanh chóng thì có thể không có trường hợp mạnh mẽ nào để ghi chép lại cho họ, trực tiếp thường là sự chuyển giao kiến ​​thức tốt nhất.

Viết lại hoặc xóa thông tin lỗi thời ngay lập tức , như mã chết càng lâu thì càng khó phát hiện và càng tích lũy nhiều thông tin. Nếu bạn không có thời gian chỉ cần xóa nó và đánh dấu bài viết là cần làm lại, nó sẽ làm bạn chậm lại và được lưu trữ trong kiểm soát phiên bản.

Thủ tục tài liệu bằng cách tự động hóa chúng trong một tập lệnh hoặc tập tin cài đặt. Mặt khác giữ chúng trong wiki, nhưng mỗi khi ai đó sử dụng một quy trình từ wiki, hãy bảo họ cố gắng cải thiện bài viết hoặc tự động hóa các phần của quy trình.

Bài viết blog thuộc về blog . Nếu mọi người muốn chia sẻ ý kiến ​​cá nhân và lời khuyên của họ, hãy tạo một blog công ty cho điều đó. Có lẽ họ không muốn bài viết của mình bị sửa đổi và dù sao cũng không ai sửa đổi chúng, vì vậy đừng để chúng làm lộn xộn wiki.

Tài liệu nên được coi là có thể cung cấp và do đó tuân theo các quy tắc truy xuất nguồn gốc và chấp nhận, cũng như đưa ra lượng thời gian thích hợp để được phát triển.

Không có gì lạ khi thấy mọi người "mong đợi" tài liệu phần mềm sẽ được cung cấp, khi nó không.

Triệt để nhưng hiệu quả. Nếu ai đó đã viết một mô-đun mới nhưng không ghi lại nó - hãy mở lại tác vụ trong trình theo dõi vấn đề và nếu cần thiết thì không được gửi tất cả mã nguồn không được ghi lại. Nếu bạn cho phép các nhà phát triển coi tài liệu mã nguồn là điều xấu cần thiết, bạn sẽ kết thúc với các mẩu tài liệu rời rạc và lỗi thời.

Trong dự án gần đây của tôi, chúng tôi có xu hướng ít nhất là theo dõi tất cả các thư viện bên thứ ba cần thiết. Nếu ai đó giới thiệu thư viện mới, nhưng nó không được ghi lại - chúng tôi sẽ khôi phục lại giải pháp cho đến khi tài liệu được giới thiệu. Nếu không có cách tiếp cận triệt để như vậy sẽ có sự hỗn loạn. Ví dụ: nhà phát triển chưa có kinh nghiệm có thể sử dụng thư viện có giấy phép mâu thuẫn với giấy phép phần mềm của chúng tôi.

Nếu một cái gì đó thay đổi nhanh chóng, nó không nên được duy trì bên ngoài mã.

động lực đằng sau các quyết định thiết kế cho các bộ phận của API

Điều này đặc biệt quan trọng để theo sát mã. Như trong, trong cùng một tập tin nguồn. Theo cách đó, sẽ khó hơn một chút để bỏ qua bất cứ khi nào ai đó chạm vào tệp và nhắc nhở gửi ít hơn tới TheD DailyWTF bởi những người không biết rằng tài liệu bên ngoài tồn tại.

Sự xuống cấp thông thường. Mã thay đổi, wiki vẫn giữ nguyên.

Đây là nơi "tài liệu thực thi" - kiểm tra đơn vị - trở nên rất hữu ích. Nếu mã thay đổi và các thử nghiệm không thay đổi cùng với nó, thì quá trình xây dựng bị phá vỡ. Tất nhiên, viết bài kiểm tra như tài liệu cần một số kỹ năng. Nhưng viết tài liệu bên ngoài cũng tốt.

Một cách tốt để giải quyết vấn đề, là biến nó thành một phần của quy trình. Nếu bạn có theo dõi mã lên đến / tham chiếu các trang có liên quan trên wiki, nhà phát triển có thể dễ dàng tìm ra những gì có thể cần được cập nhật. Ngoài ra, làm cho người đánh giá có trách nhiệm trong việc xem xét mã để đảm bảo rằng wiki được cập nhật (liên quan đến bản cập nhật).

Một cách khác để thêm nó như một phần của quy trình - vì bạn đang sử dụng một mô hình nhanh, một phần của quy trình lập kế hoạch cho các lần lặp, có thể là cập nhật các thay đổi được lên kế hoạch trong wiki. Wiki sau đó đóng vai trò là "đây là cách mọi thứ hoạt động".

Nếu bạn đang sử dụng ngôn ngữ .net, hãy xem ( Sandcastle ) lấy tài liệu XML (/// trong C #) và chuyển đổi nó thành định dạng trợ giúp MSDN.

Định dạng bao gồm mô tả, nhận xét và có khả năng bao gồm các mẫu mã, cũng như một số tính năng khác. Bạn có thể xuất thành các định dạng .CHM, .HsX, .MSCH và HTML / ASP.NET. Dự án thực tế được thêm vào giải pháp của bạn và được xây dựng trên máy chủ xây dựng. Chúng tôi đã thực hiện điều này và triển khai lên một trang web mỗi lần phát hành và người tiêu dùng thích nó vì tài liệu này có liên quan đến bản phát hành và được cập nhật liên tục.

Bạn cũng có thể chỉ định những gì cần bao gồm trong tài liệu. Hiện tại chúng tôi có 2 dự án: một cho người tiêu dùng bên ngoài chỉ bao gồm các hợp đồng và các mặt hàng phù hợp (lớp, enum, v.v.) và một cho các nhà phát triển nội bộ bao gồm mọi thứ trong API, bao gồm các mục được gắn cờ riêng và nội bộ.

Đây đã trở thành tài liệu duy nhất chúng tôi sử dụng, vì động lực và sự kỳ quặc khi sử dụng API có thể được bao gồm trong phần Nhận xét của tài liệu. Quá trình hoạt động tốt nơi tôi làm việc.

Tôi sẽ tập trung vào hai lĩnh vực, 1) Mã. 2) Không có mã ghi chú và tài liệu.

1) Mã.

Cố gắng làm cho nó tự tài liệu. Trước đây tôi thấy điều đó thường được khuyên nhưng hiếm khi được giải thích rõ ràng, vì vậy ...

Thay vì loại mã giả này:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Làm mã trông giống như thế này:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Sử dụng kiểm soát nguồn để theo dõi thông tin 'ai đã làm gì khi nào'.

2) Mã không

Sử dụng định dạng wiki và markdown để duy trì thông tin này. Làm cho nó một phần của công việc. Công khai nó, đăng nó và viết blog. Thiết lập một cuộc họp tiêu chuẩn hàng tuần hoặc hàng tháng để xem xét các công cụ cũ và mới. Làm cho nó trở thành một câu thần chú mà khi ai đó hỏi về điều gì đó, câu trả lời được đưa ra ... cùng với suy nghĩ "điều này có nên ở wiki cho lần tiếp theo ai đó hỏi không?"