Chú thích mã nguồn với sơ đồ là nhận xét

Tôi viết rất nhiều mã (chủ yếu là c ++ và javascript) chạm vào hình học và đồ họa tính toán và các loại chủ đề đó, vì vậy tôi thấy rằng sơ đồ trực quan là một phần không thể thiếu trong quá trình giải quyết vấn đề.

Tôi đã xác định ngay bây giờ rằng "ồ, sẽ không tuyệt vời nếu tôi bằng cách nào đó có thể đính kèm một sơ đồ vẽ tay vào một đoạn mã như một nhận xét", và điều này sẽ cho phép tôi quay lại với một cái gì đó mà tôi đã làm việc, ngày, tuần, tháng sớm hơn và nhanh chóng tìm lại thuật toán của tôi.

Là một người học trực quan, tôi cảm thấy như thế này có khả năng cải thiện năng suất của tôi với hầu hết mọi loại lập trình bởi vì các sơ đồ đơn giản có thể giúp hiểu và suy luận về bất kỳ loại cấu trúc dữ liệu không tầm thường nào. Đồ thị chẳng hạn. Trong lớp lý thuyết đồ thị ở trường đại học, tôi chỉ có thể thực sự hiểu được các mối quan hệ đồ thị mà tôi thực sự có thể vẽ các biểu diễn sơ đồ.

Vì thế...

Không có IDE theo hiểu biết của tôi cho phép bạn lưu hình ảnh dưới dạng nhận xét vào mã.

Suy nghĩ của tôi là tôi hoặc người khác có thể đưa ra một số công cụ khá dễ sử dụng có thể chuyển đổi hình ảnh thành chuỗi nhị phân base64 mà sau đó tôi có thể chèn vào mã của mình.

Nếu quá trình chuyển đổi / chèn có thể được sắp xếp hợp lý, nó sẽ cho phép kết nối tốt hơn nhiều giữa sơ đồ và mã thực tế, vì vậy tôi không còn cần phải tìm kiếm theo thời gian qua sổ ghi chép của mình. Tuyệt vời hơn nữa: các plugin để IDE tự động phân tích cú pháp và hiển thị hình ảnh. Hoàn toàn không có gì khó khăn về điều này từ quan điểm lý thuyết.

Tôi đoán là tôi sẽ mất thêm thời gian để thực sự tìm ra cách mở rộng các IDE yêu thích của mình và duy trì các plugin này, vì vậy tôi hoàn toàn hài lòng với một loại bộ xử lý hậu mã sẽ thực hiện phân tích tương tự và kết xuất các hình ảnh và hiển thị chúng cạnh nhau với mã, bên trong trình duyệt hoặc một cái gì đó. Vì tôi là một lập trình viên javascript bằng thương mại.

Mọi người nghĩ gì? Bất cứ ai sẽ trả tiền cho điều này? Tôi sẽ. Nhưng có lẽ tôi cũng chỉ ra rằng bất kể tôi hoặc một số lượng đáng kể đồng nghiệp của tôi sẽ trả tiền cho điều đó, cách duy nhất một điều như vậy có khả năng thành công sẽ là thông qua một bản phát hành nguồn mở.

Còn plugin Chèn hình ảnh cho Visual Studio thì sao?

Nếu bạn đang sử dụng một IDE khác và nó không hỗ trợ các hình ảnh nhúng hoặc bạn không có thời gian để mở rộng nó, vậy thì việc đặt một liên kết đến một hình ảnh trong các bình luận, trong khi hình ảnh sẽ nằm ở đâu đó trong kho lưu trữ ?

Nếu bạn không phải là nghệ sĩ ASCII , bạn có thể sử dụng doxygen làm công cụ tài liệu cùng với dot / graphviz được tích hợp với nó.

Điều này cho phép viết mô tả văn bản của đồ thị và hiển thị chúng trong tài liệu.

Ví dụ, mô tả này:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

ám chỉ như:

Bạn có thể thử chế độ nghệ sĩ emacs. Nó sẽ làm nghệ thuật ascii chứ không phải hình ảnh, vì vậy nó có thể hoặc không phải là những gì bạn đang tìm kiếm. Đặc biệt, nếu IDE của bạn không làm phông chữ có chiều rộng cố định, nó sẽ không hữu ích. Là văn bản đơn giản, nó sẽ chơi rất độc đáo với kiểm soát phiên bản.

Đây là một screencast của chế độ nghệ sĩ đang được sử dụng, vì vậy bạn có thể có ý tưởng nếu bạn quan tâm hay không.

Để khởi động chế độ nghệ sĩ trong emacs, hãy thực hiện Alt-x, nhập chế độ nghệ sĩ và nhấn return. Nút chuột giữa đưa lên menu. Các keybindings để cắt và dán không phải là các cửa sổ bình thường theo mặc định, nhưng bạn có thể bật chế độ CUA để thay đổi điều đó.

Mọi người nghĩ gì? Bất cứ ai sẽ trả tiền cho điều này? Tôi sẽ.

ZOMG, tôi phù hợp với một thể loại tương tự như bạn và sẽ thích một tính năng như vậy trực tiếp trong IDE.

Bây giờ tôi chỉ có xu hướng làm nhiều "nghệ thuật" ASCII như thế này:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

Giá trị chính tôi tìm thấy là nhìn thấy các tên biến tương ứng với sơ đồ trực quan, đặc biệt là khi chúng tôi sử dụng các đường ngang phức tạp của các mắt lưới và như vậy cho các thuật toán lưới mới. Thủ thuật tạo đồ thị doxygen này được thể hiện trong một trong những câu trả lời là rất tuyệt - tôi nên thử nhiều hơn thế.

Có rất nhiều điều dễ dàng hơn để giao tiếp trực quan là tốt, thậm chí không nhất thiết phải sử dụng biểu đồ. Thí dụ:

... Hoặc điều này (so sánh thuật toán của tôi, tôi đang gọi "phân khu hook" với phân khu CC tiêu chuẩn như Pixar sử dụng):

Nó sẽ cung cấp cho mã rất nhiều ngữ cảnh để xem những gì các hoạt động này làm và cách chúng khác nhau bên trong mã bởi vì một số thứ được hiển thị tốt nhất một cách trực quan. Hình ảnh thực sự có thể chụp một ngàn từ.

Vì vậy, nó sẽ hoàn toàn mơ mộng đối với tôi khi có một IDE cho phép tôi xem mã và hình ảnh cạnh nhau, cho phép tôi nhúng hình ảnh vào mã nguồn.

Đặc biệt là khi chúng tôi phát minh ra các thuật toán mới, thật khó để tìm ra một cách hay để mô tả chúng rất chính xác (từ góc độ kỹ thuật, không chính xác là quan điểm người dùng) mà không đi vào các bước thuật toán của chúng vì không có gì để so sánh trực tiếp với chúng. Những loại hình ảnh trước và sau có xu hướng hoàn toàn hiển thị những gì bạn có thể mong đợi từ thuật toán ngay lập tức.

Một điều tôi mơ ước là một trình gỡ lỗi trực quan cho phép tôi lập trình nó để tôi có thể làm cho một số loại dữ liệu của mình xuất ra một hình ảnh vào trình gỡ lỗi, ví dụ, để xem kết quả một cách trực quan khi tôi bước qua mã và đảm bảo các thuật toán Tôi đang cố gắng phát minh đang hoạt động chính xác ở mọi bước và phù hợp với cách tôi vẽ nó ra giấy. Ví dụ: làm cho cấu trúc dữ liệu lưới của tôi xuất ra một hình ảnh được hiển thị trong cửa sổ xem trình gỡ lỗi - lý tưởng nếu tôi thậm chí có thể xoay chế độ xem và ngay lúc đó và ở đó.

Ngoài ra, khi làm việc trong các cơ sở mã quy mô rất lớn (hàng chục triệu LỘC) được viết bởi các nhóm lỏng lẻo với hàng ngàn plugin, đôi khi nó có thể là một cơn ác mộng khi tìm ra cách thực thi mã mà chúng tôi đang tìm kiếm để che giấu, plugin hiếm khi được sử dụng từ UI. Sẽ rất tuyệt vời trong những trường hợp đó nếu mã có thể nhúng một ảnh chụp màn hình thu nhỏ cho thấy cách thực sự gọi mã đó từ giao diện người dùng (đôi khi có thể bị lỗi thời, nhưng thường thì các UI không ổn định như vậy các phiên bản để hiển thị ảnh chụp màn hình cũ vô dụng).

Bất cứ ai sẽ trả tiền cho điều này? Tôi sẽ.

Vì vậy, dù sao, yeah, hoàn toàn! Tôi muốn cái đó!!!

Âm thanh giống như một trường hợp sử dụng cho Lập trình biết chữ , nơi bạn có thể thêm sơ đồ và bất cứ điều gì vào tài liệu của bạn.

Doxygen cho phép bạn chèn hình ảnh vào các bình luận như thế này:

  /*! Here is a snapshot of my new application:
   *  \image html application.jpg
   */

Thật không may, có vẻ như không có IDE nào sẽ hiển thị những hình ảnh này theo dòng, nhưng tôi nghi ngờ rằng sẽ không quá khó để viết một phần mở rộng VSCode để làm điều đó chẳng hạn.

Tôi cũng đã tìm thấy một phần mở rộng VSCode đã hỗ trợ điều này với một nhận xét cú pháp khác . Điều này thực hiện thông qua một di chuột:

VSCode đang thêm một tính năng cho phép hình ảnh nội tuyến - "chèn mã" - nhưng dường như nó chưa sẵn sàng.

Đây là một ảnh chụp màn hình từ tiện ích mở rộng mẫu (mà tôi thực sự không thể tìm thấy - có lẽ chưa được phát hành vì API chèn mã chưa được phát hành)