Làm thế nào để làm tài liệu cho mã và tại sao phần mềm (thường) được ghi chép kém?

Có một số ví dụ tốt về mã tài liệu tốt ngoài kia, chẳng hạn như java api. Nhưng, rất nhiều mã trong các dự án công cộng như git và các dự án nội bộ của các công ty là tài liệu kém và không thân thiện với người mới.

Trong tất cả các gợi ý phát triển phần mềm của tôi, tôi đã phải đối phó với mã tài liệu kém. Tôi nhận thấy những điều sau đây -

1. Ít hoặc không có ý kiến ​​trong mã.
2. Tên phương thức và biến không tự mô tả.
3. Có rất ít hoặc không có tài liệu nào về cách mã phù hợp với hệ thống hoặc quy trình kinh doanh.
4. Thuê các nhà phát triển xấu hoặc không tư vấn cho những người tốt. Họ không thể viết mã đơn giản và sạch sẽ. Do đó, khó khăn hoặc không thể đối với bất kỳ ai, kể cả nhà phát triển để ghi lại mã.

Kết quả là tôi đã phải trải qua rất nhiều mật mã và nói chuyện với nhiều người để học hỏi. Tôi cảm thấy điều này làm lãng phí thời gian của mọi người. Nó cũng tạo ra sự cần thiết cho các phiên chuyển KT / Kiến thức cho người mới tham gia dự án.

Tôi đã học được rằng tài liệu không được chú ý vì những lý do sau:

1. Lười biếng.
2. Các nhà phát triển không muốn làm bất cứ điều gì ngoài mã.
3. An ninh công việc. (Nếu không ai có thể hiểu mã của bạn một cách dễ dàng, thì bạn có thể không dễ dàng thay thế.)
4. Thời hạn khó khăn để lại ít thời gian để tài liệu.

Vì vậy, tôi tự hỏi liệu có cách nào để khuyến khích và thực thi các thực hành tài liệu tốt trong một công ty hoặc dự án. Các chiến lược được sử dụng để tạo tài liệu phong nha cho các hệ thống và mã của bất kỳ dự án nào, bất kể sự phức tạp của nó là gì? Có ví dụ nào hay khi cần tối thiểu hoặc không cần tài liệu không?

IMHO, tôi cảm thấy rằng chúng ta nên có một đánh giá tài liệu sau khi một dự án được giao. Nếu nó không đơn giản, ngắn gọn, minh họa và thân thiện với người dùng, nhà phát triển hoặc kỹ sư tài liệu kỹ thuật có trách nhiệm với nó và được thực hiện để sửa nó. Tôi không hy vọng mọi người tạo ra các tài liệu, không hy vọng rằng nó sẽ thân thiện với người dùng như những cuốn sách đầu tiên, nhưng tôi hy vọng nó sẽ loại bỏ nhu cầu phân tích hàng giờ và các phiên KT lãng phí.

Có cách nào để chấm dứt hoặc làm giảm bớt sự điên rồ này? "Phát triển theo định hướng tài liệu" có lẽ?

Làm thế nào để mã tài liệu?

Bạn đã có một gợi ý: hãy xem cách Java API được ghi lại.

Tổng quát hơn, không có bộ quy tắc duy nhất áp dụng cho mọi dự án. Khi tôi làm việc trong các dự án quy mô lớn kinh doanh, tài liệu này không liên quan gì đến thư viện tôi sẽ viết cho một thư viện nguồn mở nhỏ, do đó, không liên quan gì đến tài liệu của dự án cá nhân quy mô trung bình của tôi .

Tại sao nhiều dự án nguồn mở không được ghi chép tốt?

Bởi vì hầu hết các dự án nguồn mở được thực hiện bởi những người đóng góp cho các dự án đó bởi vì nó thú vị. Hầu hết các lập trình viên và nhà phát triển cho rằng viết tài liệu không đủ thú vị để được thực hiện miễn phí.

Tại sao nhiều dự án nguồn đóng không được ghi chép tốt?

Bởi vì nó tiêu tốn một số tiền rất lớn để (1) viết tài liệu tốt và (2) duy trì nó.

1. Các chi phí ngay lập tức (chi phí viết tài liệu) có thể thấy rõ cho các bên liên quan: nếu nhóm của bạn yêu cầu dành hai tháng tiếp theo để làm tài liệu cho dự án, thì phải trả thêm hai tháng tiền lương.

2. Chi phí dài hạn (chi phí duy trì tài liệu) trở nên dễ nhận thấy cũng khá dễ dàng đối với các nhà quản lý và thường là mục tiêu đầu tiên khi họ phải giảm chi phí hoặc rút ngắn thời gian trì hoãn. Điều này gây ra một vấn đề bổ sung về tài liệu lỗi thời nhanh chóng trở nên vô dụng và cực kỳ tốn kém để cập nhật.

3. Tiết kiệm dài hạn (tiết kiệm từ việc không phải lãng phí vài ngày để khám phá mã kế thừa chỉ để hiểu một điều cơ bản cần được ghi nhận từ nhiều năm trước), mặt khác, rất khó đo lường, điều này khẳng định cảm giác của một số nhà quản lý rằng viết và duy trì tài liệu là một sự lãng phí thời gian.

Điều tôi thường quan sát là:

1. Khi bắt đầu, nhóm sẵn sàng ghi chép rất nhiều.

2. Theo thời gian, áp lực của thời hạn và thiếu quan tâm khiến việc duy trì tài liệu ngày càng khó khăn hơn.

3. Vài tháng sau, một người mới tham gia dự án thực tế không thể sử dụng tài liệu này, vì nó hoàn toàn không tương ứng với hệ thống thực tế.

4. Nhận thấy rằng, quản lý đổ lỗi cho các nhà phát triển không duy trì tài liệu; Các nhà phát triển yêu cầu dành một vài tuần để cập nhật nó.

   • Nếu quản lý cấp một vài tuần cho điều đó, chu kỳ lặp lại.

   • Nếu quản lý từ chối, dựa trên kinh nghiệm trước đó, nó chỉ làm tăng trải nghiệm xấu, vì sản phẩm thiếu tài liệu, nhưng một vài tháng đã dành để viết và duy trì nó.

Tài liệu nên là một quá trình liên tục, giống như thử nghiệm. Dành một tuần chỉ đơn giản là mã hóa vài ngàn LỘC, và quay lại kiểm tra và tài liệu là rất, rất đau đớn.

Làm thế nào để khuyến khích nhóm viết tài liệu?

Tương tự như các cách để khuyến khích mọi người viết mã sạch, thực hiện tái cấu trúc thường xuyên, sử dụng các mẫu thiết kế hoặc thêm các bài kiểm tra đơn vị đủ.

• Dẫn bằng ví dụ. Nếu bạn viết tài liệu tốt, các cặp của bạn cũng có thể bắt đầu làm điều đó.

• Thực hiện đánh giá mã hệ thống, bao gồm đánh giá mã chính thức nhằm mục đích kiểm tra tài liệu.

• Nếu một số thành viên của nhóm đặc biệt ác cảm với tài liệu tốt (hoặc tài liệu hoàn toàn), hãy thảo luận riêng với họ, để hiểu những trở ngại nào ngăn họ viết tài liệu tốt hơn. Nếu họ đổ lỗi cho việc thiếu thời gian, bạn sẽ thấy nguồn gốc của vấn đề.

• Làm cho sự hiện diện hoặc thiếu tài liệu có thể đo lường được trong vài tuần hoặc vài tháng, nhưng đừng tập trung vào đó. Ví dụ: bạn có thể đo số lượng bình luận trên mỗi LỘC, nhưng đừng biến nó thành thước đo vĩnh viễn, nếu không, các nhà phát triển sẽ bắt đầu viết những bình luận dài nhưng vô nghĩa chỉ để loại bỏ điểm thấp.

• Sử dụng gamification. Điều này đi kèm với điểm trước.

• Sử dụng củng cố tích cực / tiêu cực .

• (Xem bình luận của SJuan76 ) Hãy coi việc thiếu bình luận là lỗi. Ví dụ: trong Visual Studio, bạn có thể kiểm tra một tùy chọn để tạo tài liệu XML. Nếu bạn cũng kiểm tra xem tất cả các cảnh báo được coi là lỗi, việc thiếu một bình luận ở đầu một lớp hoặc một phương thức sẽ dừng quá trình biên dịch.

  Đối với ba điểm trước, điểm này nên được sử dụng một cách thận trọng. Tôi đã sử dụng nó trong một thời gian với một nhóm lập trình viên mới bắt đầu đặc biệt khó khăn và kết thúc với những bình luận tuân thủ StyleCop như thế:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

đó là, hm ..., không đặc biệt hữu ích.

Hãy nhớ rằng: không có gì tự động có thể giúp bạn xác định các bình luận xấu khi lập trình viên muốn liên lạc với bạn . Chỉ đánh giá mã và các nhiệm vụ khác của con người sẽ giúp.

Có ví dụ nào hay khi cần tối thiểu hoặc không cần tài liệu không?

Tài liệu giải thích kiến ​​trúc và thiết kế là không cần thiết:

• Đối với một nguyên mẫu,

• Đối với một dự án cá nhân được viết trong vài giờ để hoàn thành một nhiệm vụ, trong khi khá chắc chắn rằng dự án này sẽ không được duy trì nữa,

• Đối với bất kỳ dự án nào rõ ràng, với kích thước nhỏ của nó, cùng với mã đặc biệt sạch, bạn sẽ dành nhiều thời gian để viết tài liệu hơn tất cả các nhà bảo trì trong tương lai khám phá mã.

Theo một số nhà phát triển, tài liệu trong mã (mã nhận xét) không cần thiết. Đối với họ, sự hiện diện của các bình luận, ngoại trừ trong các trường hợp hiếm hoi, không phải là một dấu hiệu tốt, nhưng một dấu hiệu cho thấy mã không được tái cấu trúc đủ để rõ ràng mà không cần bình luận.

Tôi cảm thấy rằng chúng ta nên có một đánh giá tài liệu sau khi một dự án được giao.

Nếu dự án của bạn được giao ít nhất một lần mỗi tuần, đó là cách để đi. Nếu dự án của bạn không nhanh nhẹn và được giao trong khoảng thời gian sáu tháng, thì hãy đánh giá thường xuyên hơn.

Tôi nghĩ bạn nên phân biệt giữa các bình luận và tài liệu. Trong khi các bình luận là mô tả, chúng thiếu tính nhất quán, chúng nằm rải rác trên tất cả các mã. Nhận xét không bao giờ nên bù cho mã không đủ tự mô tả, thay vào đó nó sẽ gợi ý các lập trình viên khác ở những phần khó khăn.

Liệu mã có nên được ghi lại hay không phụ thuộc vào quy mô của dự án. Chắc chắn có những người tin rằng mọi thứ nên được ghi lại, và có vẻ dễ dàng biện minh cho suy nghĩ đó bởi vì ai dám chống lại kiến ​​thức tài liệu? May mắn thay, phát triển phần mềm không phải là khoa học và thế giới sẽ không sụp đổ nếu các chi tiết đằng sau chương trình nhỏ của bạn trở nên mơ hồ. Bây giờ liên quan đến một phần mềm chuyên nghiệp được sử dụng bởi nhiều nhà phát triển, vâng, rõ ràng bạn nên ghi lại mã của mình. Nhưng nếu bạn ở vị trí để viết mã ở cấp độ đó, thì rõ ràng bạn sẽ biết điều đó.

tl; dr

Nếu bạn yêu cầu mọi dự án đều được ghi chép tốt, thì bạn đang yêu cầu quá nhiều.