Tại sao không có tổng quan mã cho các dự án nguồn mở? [đóng cửa]

Có những dự án nguồn mở rất phức tạp ngoài kia, và với một số trong số chúng tôi nghĩ rằng tôi có thể đóng góp và tôi ước mình có thể, nhưng rào cản gia nhập quá cao vì một lý do duy nhất: thay đổi một dòng mã tại dự án lớn bạn phải hiểu tất cả về nó.

Bạn không cần phải đọc tất cả mã (ngay cả khi bạn đọc, nó sẽ không đủ) và hiểu tất cả các dòng duy nhất và tại sao, bởi vì mã có thể được mô đun hóa và đồng bộ hóa, do đó, có sự trừu tượng hóa, nhưng thậm chí sau đó bạn cần để có được một cái nhìn tổng quan của dự án, do đó bạn có thể biết nơi là những mô-đun, nơi thực hiện một giao diện mô-đun với khác, những gì chính xác từng module làm và lý do tại sao , và trong đó các thư mục và các tập tin là mỗi người trong số những điều này xảy ra.

Tôi đang gọi tổng quan về mã này , như tên của một phần mà các dự án nguồn mở có thể có trong trang web hoặc tài liệu giải thích mã của họ cho người ngoài. Tôi nghĩ rằng nó sẽ có lợi cho những người đóng góp tiềm năng , vì họ sẽ có thể xác định những nơi họ có thể xây dựng, các lập trình viên chính thực sự có liên quan, vì họ có thể, trong khi viết mọi thứ, sắp xếp lại tâm trí của họ, và sẽ giúp người dùng , như họ sẽ được giúp đỡ để hiểu và báo cáo tốt hơn các lỗi họ gặp phải và thậm chí có thể trở thành người đóng góp.

Nhưng tôi vẫn chưa bao giờ thấy một trong những "tổng quan mã" này. Tại sao? Có những thứ như thế này và tôi đang thiếu chúng? Những điều làm công việc tương tự như tôi đang mô tả? Hay đây là một ý tưởng hoàn toàn vô dụng, vì mọi người, ngoại trừ tôi, có thể hiểu các dự án với hàng ngàn dòng mã một cách dễ dàng?

Bởi vì đó là nỗ lực thêm để tạo và duy trì một tài liệu như vậy và quá nhiều người không hiểu các lợi ích liên quan.

Nhiều lập trình viên không phải là nhà văn kỹ thuật giỏi (mặc dù nhiều người là vậy); họ hiếm khi viết tài liệu nghiêm ngặt cho con người, vì vậy họ không thực hành và không thích làm việc đó. Viết tổng quan về mã cần có thời gian mà bạn không thể dành cho mã hóa và lợi ích ban đầu cho dự án luôn lớn hơn nếu bạn có thể nói "Chúng tôi hỗ trợ cả ba biến thể mã hóa" thay vì "Chúng tôi có những giải thích thực sự gọn gàng về mã của chúng tôi!" Quan niệm rằng một tài liệu như vậy sẽ thu hút nhiều nhà phát triển hơn nên về lâu dài sẽ có nhiều mã được viết không chính xác đối với họ, nhưng nó được coi là một canh bạc không chắc chắn; văn bản này có thực sự tạo ra sự khác biệt giữa việc chộp lấy một cộng tác viên hay không? Nếu tôi tiếp tục viết mã ngay bây giờ , làm điều này được thực hiện

Một tài liệu tổng quan về mã cũng có thể khiến mọi người cảm thấy phòng thủ; thật khó để mô tả các quyết định cấp cao hơn mà không cảm thấy cần phải biện minh cho chúng, và rất thường mọi người đưa ra quyết định mà không có lý do "nghe có vẻ đủ tốt" khi thực sự được viết. Ngoài ra còn có một hiệu ứng liên quan đến điều đã nói ở trên: vì việc cập nhật văn bản cho phù hợp với mã thay đổi gây ra nỗ lực bổ sung, điều này có thể ngăn cản việc quét các thay đổi đối với mã. Đôi khi sự ổn định này là một điều tốt, nhưng nếu mã thực sự cần viết lại ở mức trung bình, nó sẽ biến thành một trách nhiệm pháp lý.

Sự thật khô khan, khắc nghiệt?

Tài liệu không được thực hiện bởi vì các dự án có thể làm mà không có nó.

Ngay cả các dự án nguồn mở thường phải đối mặt với cạnh tranh gay gắt. Hầu hết các dự án như vậy không bắt đầu với vai lớn, họ bắt đầu một ý tưởng sáng, thường là một ý tưởng sáng chói.

Như vậy, họ không thể dành thời gian và chi phí thuê nhân viên tài liệu, ngay cả khi họ đề nghị hợp tác miễn phí. Một dự án tài liệu, nguyên vẹn, thường đã trải qua một số lần lặp đầu tiên. Nó thường bắt đầu với 1-3, có thể 5 chàng trai viết ra ý tưởng tiểu thuyết của họ và đưa nó ra thế giới như một bằng chứng về khái niệm. Nếu ý tưởng chứng minh tốt thì "người theo dõi" có thể thêm vào, họ có xu hướng bắt đầu yêu cầu tiện ích mở rộng, tùy chọn mới, bản dịch ... Tại thời điểm này, mã vẫn là nguyên mẫu, thường có các tùy chọn và thông báo được mã hóa cứng.

Không phải tất cả các dự án nguồn mở đều vượt quá giai đoạn này, chỉ những dự án phá vỡ "khối lượng quan trọng" cần thiết để thu hút sự quan tâm của công chúng. Hơn nữa, một trong những nhà phát triển ban đầu phải "nghĩ lớn và xa" và lên kế hoạch mở rộng, v.v. Anh ta cũng có thể trở thành "nhà truyền giáo" dự án và đôi khi cũng là "người quản lý dự án" (lần khác là những người khác nhau). Đó là một bước cần thiết để đưa dự án đi lên, từ bằng chứng về khái niệm đến thực tế thành lập ngành.

Thậm chí sau đó, người quản lý dự án có thể chọn không tạo tài liệu.

Một dự án đang phát triển, năng động sẽ bị chậm lại và tài liệu sẽ thực sự bị tụt hậu so với mã trong khi nó được tăng cường thực sự khó khăn, để thực hiện các bản dịch, tùy chọn, cắm trình quản lý ...

Điều thường xảy ra là:

1. Một tài liệu giới thiệu ngắn gọn được thực hiện, về dự án là gì và nơi nó sẽ đến ("lộ trình" nổi tiếng).
2. Nếu có thể, một API được phát triển và một API được bầu là "mã tài liệu" trên phần lớn mã cơ bản.
3. Đặc biệt là API mà cả mã khác cũng được định dạng lại và "PHPdoc" / "Javadoc", v.v., các bình luận đặc biệt được thêm vào. Họ cung cấp một sự thỏa hiệp hợp lý giữa thời gian và phần thưởng: ngay cả một lập trình viên khiêm tốn thường biết cách viết một lớp mô tả các chức năng của anh ta, các tham số cũng được ghi lại "tự động" và toàn bộ được gắn với mã liên quan của nó và do đó họ tránh được tài liệu " bỏ đi "và chậm phát triển.
4. Thông thường, một diễn đàn được tạo ra. Đó là một phương tiện truyền thông xã hội mạnh mẽ, nơi người dùng cuối và lập trình viên có thể nói chuyện với nhau (và giữa các đồng nghiệp của họ, có thể trong các tiểu mục "chỉ dành cho nhà phát triển"). Điều này cho phép rất nhiều kiến ​​thức xuất hiện từ từ và được củng cố bởi cộng đồng được thực hiện (đọc: không cân nhắc về nhóm nhà phát triển) Câu hỏi thường gặp và HOWTO.
5. Trong các dự án thực sự lớn, một wiki cũng được sản xuất. Tôi tuyên bố "các dự án lớn" bởi vì họ thường là những người có đủ người theo dõi để tạo wiki (một nhà phát triển) và sau đó thực sự lấp đầy nó ngoài "xương sống" (cộng đồng làm).

Tài liệu tổng quan như bạn mô tả là rất hiếm ngay cả trên các dự án thương mại. Họ đòi hỏi nỗ lực thêm với ít giá trị cho các nhà phát triển. Ngoài ra các nhà phát triển có xu hướng không viết tài liệu trừ khi họ thực sự cần. Một số dự án may mắn có được những thành viên giỏi viết kỹ thuật và kết quả là có tài liệu người dùng tốt. Tài liệu dành cho nhà phát triển nếu nó tồn tại, không có khả năng được cập nhật để phản ánh các thay đổi mã.

Bất kỳ dự án được tổ chức tốt sẽ có một cây thư mục tương đối tự giải thích. Một số dự án sẽ ghi lại hệ thống phân cấp này và / hoặc lý do nó được chọn. Nhiều dự án tuân theo bố cục mã tương đối chuẩn, vì vậy nếu bạn hiểu một dự án, bạn sẽ hiểu cách bố trí của các dự án khác sử dụng cùng bố cục.

Để thay đổi một dòng mã, bạn cần hiểu biết hạn chế về mã xung quanh. Bạn không bao giờ phải hiểu toàn bộ cơ sở mã để làm như vậy. Nếu bạn có một ý tưởng hợp lý về loại chức năng bị hỏng, thường có thể điều hướng hệ thống phân cấp thư mục khá nhanh.

Để thay đổi một dòng mã, bạn cần hiểu phương thức mà dòng được tìm thấy. Nếu bạn hiểu hành vi dự kiến ​​của phương thức là gì, bạn sẽ có thể thực hiện các thay đổi chính xác hoặc các phần mở rộng cho chức năng.

Đối với các ngôn ngữ cung cấp phạm vi, bạn có thể cấu trúc lại các phương thức phạm vi riêng. Trong trường hợp này, bạn có thể cần phải thay đổi người gọi cũng như phương thức hoặc phương thức cấu trúc lại. Điều này đòi hỏi một sự hiểu biết rộng hơn, nhưng vẫn còn hạn chế, về cơ sở mã.

Xem bài viết của tôi Thêm SHA-2 vào tinyca để biết ví dụ về cách thay đổi như vậy có thể được thực hiện. Tôi có một sự hiểu biết cực kỳ hạn chế về mã được sử dụng để tạo giao diện.

Có những thứ như thế này và tôi đang thiếu chúng? Những điều làm công việc tương tự như tôi đang mô tả?

Có một cuốn sách tuyệt vời tên là Kiến trúc của các ứng dụng nguồn mở cung cấp các mô tả chi tiết về một loạt các dự án phần mềm nguồn mở cấu hình cao. Tuy nhiên, tôi không chắc liệu nó có hoàn thành chính xác vai trò mà bạn tưởng tượng hay không, bởi vì tôi tin rằng đối tượng chính của nó được dự định là các nhà phát triển tìm kiếm các mẫu để làm theo khi tạo ứng dụng của riêng họ, chứ không phải là người đóng góp mới cho các dự án có trong sách (mặc dù tôi chắc chắn rằng nó có thể hữu ích ở đó).

Bởi vì có nhiều lập trình viên nguồn mở hơn nhiều so với các nhà văn kỹ thuật nguồn mở.

Tài liệu cần bảo trì và thời gian để cập nhật. Tài liệu càng cồng kềnh thì càng mất nhiều thời gian. Và tài liệu không đồng bộ với mã còn tệ hơn vô dụng: nó đánh lừa và che giấu thay vì tiết lộ.

Một cơ sở mã tài liệu tốt là tốt hơn so với một tài liệu ít hơn, nhưng tài liệu có thể dễ dàng mất chừng nào viết mã ở nơi đầu tiên. Vì vậy, câu hỏi của bạn là, tốt hơn là có một cơ sở mã tài liệu tốt, hoặc một cơ sở mã lớn gấp đôi? Là chi phí để giữ cho tài liệu được cập nhật bất cứ khi nào thay đổi mã có giá trị đóng góp của các nhà phát triển bổ sung mà nó có thể hoặc không thể mang lại?

Mã vận chuyển thắng. Giảm số lượng nỗ lực đưa vào những thứ khác ngoài mã vận chuyển có thể khiến mã được gửi thường xuyên hơn và có nhiều khả năng vận chuyển trước khi hết tài nguyên.

Điều này không có nghĩa là những thứ bên cạnh vấn đề vận chuyển. Tài liệu bổ sung giá trị cho dự án và với một dự án đủ lớn, chi phí kết nối của việc thêm một nhà phát triển khác có thể cao hơn nhiều so với việc thêm một tài liệu. Và, như đã lưu ý, tài liệu có thể tăng đầu tư vào dự án (bằng cách giúp các lập trình viên mới tham gia dễ dàng hơn).

Tuy nhiên, không có gì bán thành công như: một dự án không hoạt động hoặc làm bất cứ điều gì thú vị hiếm khi thu hút các nhà phát triển.

Tài liệu về một cơ sở mã là một dạng của siêu công việc. Bạn có thể dành nhiều thời gian để viết ra các tài liệu ưa thích mô tả một cơ sở mã không có nhiều giá trị hoặc bạn có thể dành thời gian để tạo ra những thứ mà người tiêu dùng của cơ sở mã của bạn muốn và làm cho cơ sở mã của bạn có giá trị.

Đôi khi làm cho mọi thứ khó khăn hơn làm cho những người thực hiện nhiệm vụ tốt hơn. Do mức độ cam kết cao hơn đối với dự án (dành hàng giờ đồng hồ để học kiến ​​trúc) hoặc do thiên vị kỹ năng (nếu bạn đã là một chuyên gia về công nghệ liên quan, việc tăng tốc sẽ nhanh hơn, do đó, rào cản thiếu tài liệu như vậy ít quan trọng hơn: do đó, nhiều chuyên gia tham gia nhóm và ít người mới bắt đầu hơn).

Cuối cùng, vì những lý do đã nêu ở trên, các nhà phát triển hiện tại có khả năng là chuyên gia về cơ sở mã. Viết tài liệu như vậy không giúp họ hiểu cơ sở mã nhiều, vì họ đã có kiến ​​thức, nó chỉ giúp các nhà phát triển khác. Phần lớn sự phát triển nguồn mở dựa trên "gãi ngứa" mà nhà phát triển có với mã: thiếu tài liệu đã nói những gì nhà phát triển biết hiếm khi bị ngứa.

Bên cạnh nỗ lực thêm , một số dự án nguồn mở đang làm tê liệt tài liệu của họ nhằm mục đích, để có được công việc tự do cho người bảo trì của họ (để thực hiện một cái gì đó, hoặc tổ chức đào tạo). Không chỉ họ không có tổng quan về mã, mà API và hướng dẫn của họ rất tệ hoặc thiếu rất nhiều thứ.

Chỉ cần đặt tên một cái khá phổ biến: bluez. Chúc may mắn tìm được một hướng dẫn tốt, sau đó để quét các thiết bị gần đó.