Siêu liên kết, tài liệu mã nguồn bên ngoài [đóng]

Tại sao chúng ta vẫn nhúng các mô tả ngôn ngữ tự nhiên của mã nguồn (nghĩa là lý do tại sao một dòng mã được viết) trong mã nguồn, chứ không phải là một tài liệu riêng biệt?

Với các bất động sản mở rộng dành cho môi trường phát triển hiện đại (màn hình độ phân giải cao, màn hình kép, v.v.), IDE có thể cung cấp bảng điều khiển nửa bước trong đó mã nguồn được phân tách trực quan với - nhưng thực chất được liên kết với - ý kiến ​​tương ứng của nó. Ví dụ: các nhà phát triển có thể viết nhận xét mã nguồn bằng ngôn ngữ đánh dấu siêu liên kết (liên kết với các yêu cầu phần mềm bổ sung), điều này sẽ đồng thời ngăn tài liệu làm lộn xộn mã nguồn.

Những thiếu sót nào sẽ ức chế một cơ chế phát triển phần mềm như vậy?

Một mock-up để giúp làm rõ câu hỏi:

Khi con trỏ ở một dòng cụ thể trong mã nguồn (được hiển thị với nền màu xanh lam ở trên), tài liệu tương ứng với dòng tại con trỏ được tô sáng (nghĩa là được phân biệt với các chi tiết khác). Như đã lưu ý trong câu hỏi, tài liệu sẽ ở trạng thái khóa với mã nguồn khi con trỏ nhảy qua mã nguồn. Phím nóng có thể chuyển đổi giữa "chế độ tài liệu" và "chế độ phát triển".

Những lợi thế tiềm năng bao gồm:

• Nhiều mã nguồn và nhiều tài liệu hơn trên (các) màn hình cùng một lúc
• Khả năng chỉnh sửa tài liệu độc lập với mã nguồn (bất kể ngôn ngữ?)
• Viết tài liệu và mã nguồn song song mà không có xung đột hợp nhất
• Tài liệu siêu liên kết thời gian thực với định dạng văn bản cao cấp
• Dịch máy bán thời gian thực sang các ngôn ngữ tự nhiên khác nhau
• Mỗi dòng mã có thể được liên kết rõ ràng với một nhiệm vụ, yêu cầu kinh doanh, v.v.
• Tài liệu có thể tự động đánh dấu thời gian khi mỗi dòng mã được viết (số liệu)
• Động bao gồm các sơ đồ kiến ​​trúc, hình ảnh để giải thích các mối quan hệ, vv
• Tài liệu nguồn đơn (ví dụ: đoạn mã thẻ để đưa vào hướng dẫn sử dụng).

Ghi chú:

• Cửa sổ tài liệu có thể được thu gọn
• Quy trình làm việc để xem hoặc so sánh các tệp nguồn sẽ không bị ảnh hưởng
• Làm thế nào việc thực hiện xảy ra là một chi tiết; tài liệu có thể là:
  • giữ ở cuối tập tin nguồn;
  • chia thành hai tệp theo quy ước ( filename.c, filename.c.doc); hoặc là
  • điều khiển cơ sở dữ liệu đầy đủ
• Theo tài liệu siêu liên kết, tôi có nghĩa là liên kết với các nguồn bên ngoài (như StackOverflow hoặc Wikipedia) và các tài liệu nội bộ (nghĩa là wiki trên một tên miền phụ có thể tham chiếu chéo tài liệu yêu cầu kinh doanh) và các tệp nguồn khác (tương tự JavaDocs).

Chủ đề liên quan: Điều gì có ác cảm với tài liệu trong ngành?

Vấn đề này làm phiền tôi mọi lúc, và tôi chỉ có một ý tưởng về hướng mà chúng ta sẽ cố gắng giải quyết nó (đó là cách tôi tìm thấy câu hỏi này).

Tôi nghĩ rằng vấn đề tài liệu được liên kết đã nghĩ sai khi chúng tôi quyết định đưa tài liệu người dùng vào mã nguồn. Giống như docco.

Trước hết, hãy phân biệt nhận xét mã từ tài liệu người dùng.

Bình luận mã thường là tốt nhất khi chúng ngắn, siêu ngắn trên thực tế, vì vậy tôi thực sự có thể đọc mã thực hiện công cụ mà không cần phải xem một số thơ về lý do và cách thức hoạt động.

Nhận xét của người dùng dành cho những người đang cố gắng sử dụng thư viện / API của bạn và có thể bao gồm các ví dụ về việc sử dụng, giải thích lý do tại sao nó được triển khai như vậy hoặc hướng dẫn về cách mở rộng thư viện. Loại bình luận này có xu hướng thực sự dài dòng.

Tôi đồng ý về thực tế rằng tài liệu nên được viết bằng văn bản đơn giản để không bị nhà cung cấp cố định và dễ dàng thêm vào một VCS. Nhưng tôi nghĩ rằng việc giữ tài liệu người dùng trong tệp nguồn là một sai lầm lớn vì ít nhất hai lý do:

• Khó đọc mã hơn
• Không đủ tài liệu linh hoạt (giả sử tôi cần hai trang tài liệu sử dụng cùng một mã ví dụ hoặc có một trang tài liệu cần xen kẽ mã từ hai tệp nguồn khác nhau).

Vậy tại sao chúng ta muốn có nó trong cùng một tệp? Chà, không ai muốn có tài liệu của họ không đồng bộ từ mã. Nhưng dù sao chúng tôi cũng làm được, và đặc biệt là một ngày với thành công lớn của Markdown. Mà tôi nghĩ là đang đi đúng hướng, nhưng nếu rơi ngắn, waaay ngắn.

Khi chúng tôi xen kẽ nhận xét mã với nhận xét của người dùng, chúng tôi có ràng buộc 2 chiều. Điều đó cho phép chúng ta dễ dàng xem bình luận nào tương ứng với phần nào của mã. Chúng ta cũng có thể thấy nếu một số mã không có giấy tờ. Những gì nó không cung cấp, là một cách để xem bình luận có được cập nhật hay không và điều đó xảy ra rất nhiều khi mã của bạn khó đọc (vì tài liệu làm cho nó xấu đi).

Điều gì sẽ xảy ra nếu thay vì có ràng buộc 2 chiều, chúng ta có một cách?. Tài liệu chỉ vào mã. Chúng ta có thể có mã markdown với các lệnh đặc biệt như:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Điều này có lợi ích là đánh dấu với một số bổ sung và với các công cụ thích hợp, chúng tôi có thể tăng thêm giá trị cho nó.

Hãy tưởng tượng điều này một cách ràng buộc với các công cụ như grunt (ngay cả với tác vụ đồng hồ). Bạn có thể phát hiện khi thay đổi tệp nguồn, xem tệp tài liệu nào phụ thuộc vào nó và cảnh báo người dùng (hoặc đánh dấu nó ở đâu đó) nếu mã được nhận xét đã thay đổi.

Lôi 404 Không Tim Được Trang

Khi làm việc với mã, bạn không muốn nhận xét bị mất và đó là điều sẽ xảy ra khi bạn tách mã và nhận xét thành các tài liệu riêng biệt.

Ngoài ra, theo kịp phiên bản giữa tài liệu nhận xét và tài liệu mã của bạn sẽ gây ra nhiều đau đớn hơn sau đó đạt được.

Một số đề xuất bạn thực hiện tôi thực sự thích nhưng có thể dễ dàng thực hiện trong khi cũng có mã và nhận xét trong 1 tệp.

Những bất lợi có thể có mà tôi thấy:

• Bạn cần một trình soạn thảo đặc biệt thực hiện tính năng này

• Mã không chỉ là văn bản đơn giản nữa, dễ thao tác và cam kết với VCS-es

• Bạn cần gấp đôi chiều rộng màn hình để làm việc với mã

Đối với lập luận của bạn:

Nhiều mã nguồn và nhiều tài liệu hơn trên (các) màn hình cùng một lúc

Nhưng có thể bất tiện nếu bạn muốn xem hai tệp cạnh nhau.

Khả năng chỉnh sửa tài liệu độc lập với mã nguồn (bất kể ngôn ngữ?)

Tôi sẽ tranh luận rằng nó thực sự là một bất lợi. Cá nhân tôi cố gắng giữ tài liệu càng gần mã càng tốt để nó không bị lỗi thời.

Viết tài liệu và mã nguồn song song mà không có xung đột hợp nhất

Một lần nữa, có thể là một bất lợi. Nếu tài liệu của bạn được xen kẽ sâu với mã, làm thế nào bạn có thể chỉnh sửa chúng một cách độc lập?

Tài liệu siêu liên kết thời gian thực với định dạng văn bản cao cấp

Nếu nó nằm trong mã, thì đó là thời gian thực;) Đối với các siêu liên kết, việc chuyển sang định nghĩa đã được triển khai trong hầu hết các IDE.

Dịch máy bán thời gian thực sang các ngôn ngữ tự nhiên khác nhau

Tôi không thấy lý do tại sao bạn không thể làm điều đó với các bình luận / tài liệu thông thường.

Mỗi dòng mã có thể được liên kết rõ ràng với một nhiệm vụ, yêu cầu kinh doanh, v.v.

Điều này tôi không chắc chắn về ... Không thể đạt được nó với các bình luận thường xuyên?

Tài liệu có thể tự động đánh dấu thời gian khi mỗi dòng mã được viết (số liệu)

Không VCS-es cung cấp loại thông tin này?

Đã nói điều này, tôi khá thích cách bố trí - nhưng tôi không thấy sự cần thiết phải thay đổi định dạng tệp, không khó để tạo ra nó từ các bình luận thông thường. Có một loạt các máy tạo tài liệu làm được điều đó, ví dụ như Docco và những người kế nhiệm của nó, như Pycco hoặc Marginalia .

Đầu tiên, các nhận xét tài liệu cần phải đi kèm với mã - di chuyển chúng đi nơi khác chỉ làm cho mọi thứ trở nên cực kỳ khó xử lý để đạt được mức tăng thực tế. Vậy tại sao phải bận tâm!

Những gì có thể được thực hiện mặc dù là lấy những bình luận được nhúng đó và ẩn chúng trong trình chỉnh sửa, hiển thị chúng trong một bong bóng hoặc chú giải công cụ hoặc những gì cần thiết. Tôi hy vọng rằng cách tiếp cận như vậy có thể khuyến khích mọi người viết nhiều tài liệu hơn cho mã - ví dụ: mô tả về một lớp có thể đi với lớp thay vì trong tài liệu thiết kế bên ngoài.

Hiện tại bạn có thể nhúng các siêu liên kết trong nhận xét mã và bạn có thể tạo tài liệu từ mã bằng các công cụ như Doxygen hoặc Sphinx. Tôi đoán nó sẽ chỉ cần một số phần mở rộng ưa thích, anh ấy là người biên tập mã để hỗ trợ tốt hơn cho các công cụ này.

Tôi sẽ không liên kết bất kỳ dòng mã nào với công cụ theo dõi lỗi hoặc công cụ yêu cầu, đó là công việc tốt hơn cho SCM của bạn. Sau đó, bạn có thể thấy các chỉnh sửa mã trên mỗi cam kết được liên kết với một tác vụ. Tôi sẽ không tích hợp tài liệu được lưu trữ trong mã chống lại trình theo dõi lỗi - bạn sẽ bị lừa nếu bạn muốn chuyển sang một tài liệu mới (hmm, tôi có thể thấy tính năng này được thêm vào TFS ngay bây giờ) hoặc nếu bạn mất lịch sử cam kết của bạn (xảy ra)

Ngoài những gì @Bogdan đã nêu, tôi sẽ thêm một vài điều:

• Tôi đã cấu hình IDE của mình để luôn có 2 tệp cùng một lúc. Với tính năng bạn đang đề xuất, về cơ bản tôi sẽ cần 2 màn hình để xem cùng một lượng thông tin và 3 để thực hiện những gì tôi đang làm với 2.
• Trong khi duyệt qua một tệp, bạn không thấy ngay các bình luận và nếu bạn không biết chính xác những gì bạn đang tìm kiếm, thì rất khó để tìm thấy nó.
• Trong khi tìm kiếm thông qua một tập tin, tôi không thể tìm kiếm thông qua các bình luận trực tiếp (hoặc dễ dàng).
• Đôi khi tôi cần thực hiện nhiều thử nghiệm khác nhau / viết các đoạn mã ngắn trên máy chủ trực tiếp, thông qua ssh . Mặc dù chức năng mà bạn đang nói có thể được tích hợp với VIM hoặc các trình soạn thảo dòng lệnh khác - rất có thể sẽ có những vấn đề khá lớn

• Hầu hết các IDE đều hỗ trợ thu gọn mã / bình luận , với kết quả cuối cùng là như sau:

  Thay vì bình thường:

  

Làm cho mã dễ đọc hơn, trong trường hợp bạn không cần bình luận.

Mã nguồn và tài liệu theo cách nó nên được thực hiện.

http://jasmine.github.io/2.3/int sinhtion.html