Beri anotasi kode sumber dengan diagram sebagai komentar

Saya menulis banyak kode (terutama c ++ dan javascript) yang menyentuh pada komputasi geometri dan grafik dan topik-topik semacam itu, jadi saya telah menemukan bahwa diagram visual telah menjadi bagian tak terpisahkan dari proses penyelesaian masalah.

Saya baru saja memutuskan bahwa "oh, bukankah akan fantastis jika saya bisa melampirkan diagram yang digambar tangan ke sepotong kode sebagai komentar", dan ini akan memungkinkan saya untuk kembali ke sesuatu yang saya kerjakan, hari, minggu, bulan sebelumnya dan jauh lebih cepat grok kembali algoritma saya.

Sebagai pembelajar visual, saya merasa seperti ini memiliki potensi untuk meningkatkan produktivitas saya dengan hampir setiap jenis pemrograman karena diagram sederhana dapat membantu memahami dan memberi alasan tentang segala jenis struktur data yang tidak sepele. Grafik misalnya. Selama kelas teori graf di universitas saya hanya pernah benar-benar dapat memahami hubungan grafik yang saya benar-benar dapat menggambar representasi diagram dari.

Begitu...

Tidak ada IDE yang saya tahu memungkinkan Anda menyimpan gambar sebagai komentar untuk kode.

Pemikiran saya adalah bahwa saya atau orang lain dapat membuat alat yang cukup mudah digunakan yang dapat mengubah gambar menjadi string biner base64 yang kemudian dapat saya masukkan ke dalam kode saya.

Jika proses konversi / penyisipan dapat dirampingkan cukup itu akan memungkinkan koneksi yang jauh lebih baik antara diagram dan kode aktual, jadi saya tidak perlu lagi mencari secara kronografis melalui notebook saya. Yang lebih mengagumkan: plugin untuk IDE secara otomatis mem-parsing dan menampilkan gambar. Sama sekali tidak ada yang sulit tentang ini dari sudut pandang teoretis.

Dugaan saya adalah bahwa akan membutuhkan waktu ekstra bagi saya untuk benar-benar mengetahui cara memperluas IDE favorit saya dan mempertahankan plugin ini, jadi saya akan sangat senang dengan semacam kode post-prosesor yang akan melakukan penguraian yang sama dan render gambar dan menunjukkannya berdampingan dengan kode, di dalam browser atau sesuatu. Karena saya seorang programmer javascript oleh perdagangan.

Apa yang orang pikirkan? Adakah yang akan membayar untuk ini? Saya akan. Tetapi saya mungkin juga akan menunjukkan bahwa terlepas dari apakah saya atau sejumlah besar rekan saya akan membayar untuk hal seperti itu, satu-satunya cara hal seperti itu akan berhasil adalah melalui rilis sumber terbuka.

Bagaimana dengan plugin Image Insertion untuk Visual Studio ?

Jika Anda menggunakan IDE yang berbeda dan itu tidak mendukung gambar yang disematkan atau Anda tidak punya waktu untuk memperpanjangnya, lalu bagaimana dengan menempatkan tautan ke gambar di komentar, sedangkan gambar akan berada di suatu tempat di repositori ?

Jika Anda bukan artis ASCII , Anda dapat menggunakan doxygen sebagai alat dokumentasi bersama dengan dot / graphviz yang terintegrasi dengannya.

Ini memungkinkan untuk menulis deskripsi tekstual dari grafik dan merendernya dalam dokumentasi.

Misalnya, deskripsi ini:

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)" ];
}

diterjemahkan sebagai:

Anda dapat mencoba mode artis emacs. Itu akan melakukan seni ascii daripada gambar per se, jadi mungkin atau tidak mungkin apa yang Anda cari. Secara khusus, jika IDE Anda tidak melakukan font dengan lebar tetap, itu tidak akan berguna. Menjadi teks biasa, itu akan bermain sangat baik dengan kontrol versi.

Berikut adalah screencast mode artis yang digunakan, sehingga Anda bisa mendapatkan ide jika Anda tertarik atau tidak.

Untuk memulai mode artis dalam emacs, lakukan Alt-x, ketik mode artis, dan tekan kembali. Tombol tengah mouse menampilkan menu. Ikatan kunci untuk memotong dan menempel bukan jendela yang normal secara default, tetapi Anda dapat mengaktifkan mode CUA untuk mengubahnya.

Apa yang orang pikirkan? Adakah yang akan membayar untuk ini? Saya akan.

ZOMG, saya cocok dalam kategori yang sama seperti Anda dan akan menyukai fitur seperti itu langsung di IDE.

Untuk saat ini saya cenderung melakukan banyak "seni" ASCII seperti ini:

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

Nilai utama yang saya temukan adalah melihat nama variabel yang sesuai dengan diagram visual, terutama ketika kita menggunakan traversal kompleks jerat dan semacamnya untuk algoritma mesh baru. Trik penghasil grafik oksigen yang ditunjukkan dalam salah satu jawaban ini sangat keren - saya harus mencobanya lagi.

Ada begitu banyak hal yang juga lebih mudah untuk dikomunikasikan secara visual, bahkan tidak harus menggunakan grafik. Contoh:

... atau ini (perbandingan algoritme saya yang saya panggil "hook subdivision" ke subdivisi CC standar seperti yang digunakan oleh Pixar):

Itu akan memberikan kode begitu banyak konteks untuk hanya melihat apa yang dilakukan operasi ini dan bagaimana mereka berbeda di dalam kode karena beberapa hal terbaik hanya ditampilkan secara visual. Gambar benar-benar dapat menangkap ribuan kata.

Jadi akan sangat melamun bagi saya untuk memiliki IDE yang memungkinkan saya melihat kode dan gambar berdampingan, memungkinkan saya untuk menanamkan gambar ke dalam kode sumber.

Terutama ketika kami menemukan algoritma baru, sulit untuk menemukan cara yang baik untuk menggambarkan mereka dengan sangat akurat (dari perspektif teknis, bukan perspektif pengguna) tanpa melangkah ke langkah algoritmik mereka karena tidak ada yang benar-benar membandingkannya secara langsung. Jenis gambar sebelum dan sesudah ini cenderung benar-benar menunjukkan apa yang dapat Anda harapkan dari algoritme.

Hal lain yang saya impikan adalah visual debugger yang memungkinkan saya memprogramnya sehingga saya dapat membuat beberapa tipe data saya mengeluarkan gambar ke dalam debugger, misalnya, untuk melihat hasil secara visual ketika saya sedang melangkah melalui kode dan memastikan algoritma Saya mencoba untuk menemukan bekerja dengan benar di setiap langkah dan mencocokkan cara saya menggambar di atas kertas. Sebagai contoh, buat struktur data mesh saya menghasilkan gambar yang diberikan di jendela arloji debugger - ideal jika saya bahkan dapat memutar tampilan dan semacam itu saat itu juga.

Juga ketika bekerja dalam basis kode skala sangat besar (puluhan juta LOC) yang ditulis oleh tim yang longgar dengan seribu plugin, kadang-kadang bisa menjadi mimpi buruk hanya untuk mengetahui bagaimana mengeksekusi kode yang kita cari untuk beberapa kode yang tidak jelas, Plugin yang jarang digunakan dari UI. Akan sangat luar biasa dalam kasus-kasus itu jika kode tersebut dapat menyematkan tangkapan layar miniatur yang menunjukkan bagaimana sebenarnya memohon kode itu dari antarmuka pengguna (mungkin cenderung keluar dari tanggal dari waktu ke waktu, tetapi biasanya UI tidak begitu tidak stabil di seluruh versi untuk membuat screenshot sebelumnya tidak berguna).

Adakah yang akan membayar untuk ini? Saya akan.

Jadi, ya, benar-benar! Saya mau itu!!!

Kedengarannya seperti kasus penggunaan untuk Pemrograman Literate di mana Anda dapat menambahkan diagram dan apa pun untuk dokumentasi Anda.

Doxygen memungkinkan Anda untuk memasukkan gambar dalam komentar seperti ini:

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

Sayangnya sepertinya tidak ada IDE yang akan menampilkan gambar-gambar ini sebaris, tetapi saya kira tidak akan terlalu sulit untuk menulis ekstensi VSCode untuk melakukannya misalnya.

Saya juga menemukan satu ekstensi VSCode yang sudah mendukung ini dengan commentimg sintaks yang berbeda . Ini melakukannya melalui hover:

VSCode menambahkan fitur yang memungkinkan gambar inline - "inset kode" - tetapi tampaknya belum siap.

Ini adalah tangkapan layar dari ekstensi sampel (yang sebenarnya tidak bisa saya temukan - mungkin belum dirilis karena kode inset API belum dirilis)