Beri anotasi kode sumber dengan diagram sebagai komentar


14

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.


4
Alternatif: Mengomentari tautan ke file gambar lokal yang terbuka di penampil gambar default.
Hand-E-Food

Ketakutan terbesar saya adalah penyalahgunaan sistem. Tentu itu dimulai dengan diagram yang bermakna untuk algoritma yang kompleks, tetapi berapa lama sampai seseorang mengunggah dokumen spesifikasi yang tipis ke dalam komentar untuk kelas? Sebelum Anda menyadarinya, semua yang terkait dengan proyek + pengembang dihancurkan menjadi komentar kode. Tentu saja, setiap sistem yang kuat terbuka untuk penyalahgunaan. Saya pikir kebutuhan adalah sebuah ceruk, tetapi jika Anda berada di ceruk itu akan menjadi alat yang sangat berguna.
Snixtor

@ Hand-E-Food Bagus! URL file dalam komentar muncul sebagai tautan yang dapat diklik dalam Xcode di luar kotak. Satu-satunya keluhan saya dengan ini adalah tampaknya tidak mungkin membuat URL file jalur relatif, sehingga aspek tautan yang dapat diklik terputus (kemungkinan besar) saat berpindah sistem.
Steven Lu

Anda mungkin tertarik pada grafik atau pohon
TehShrike

Saya melakukan javadoc yang akan menghasilkan HMTL, dengan gambar. Atau SimpleDocBook, dokumentasi terpisah, berbasis XML, seseorang dapat / harus merujuk ke dalam kode untuk aturan bisnis. Itu memberikan prosa yang bagus, dan mencakup sistem dari perspektif semua logika bisnis, alih-alih mendistribusikan komponen dan lapisan perangkat lunak (kelas). Setiap permintaan perubahan, tambahkan kode dengan sebagai referensi ke buku catatan + nomor versi / tiket, dan buku catatan memiliki daftar perubahan + nomor tiket. Itu bekerja karena cakupan lengkapnya. Tidak yakin bagaimana itu akan sesuai dengan situasi Anda.
Joop Eggen

Jawaban:


6

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 ?


Itu keren sekali. Saya menggunakan VS di tempat kerja sehingga saya bisa mencobanya! Terima kasih. Menyimpan gambar ke dalam repo dan entah bagaimana menghubungkannya jelas merupakan salah satu cara untuk mencapai ini, tetapi saya cukup yakin itu masih terlalu banyak pekerjaan pembukuan bagi saya untuk diimplementasikan dengan andal. Saya seorang programmer yang sangat malas.
Steven Lu

Menyimpan gambar ke dalam repo juga akan berfungsi dengan sebagian besar metode penjelajahan repo (mis. Antarmuka web repo VCS)
Steven Lu

4

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:

masukkan deskripsi gambar di sini


Itu keren! Adakah alat bantu yang mendukung lingkungan Java? Saya tidak bisa melihat apa pun yang menyerupai dukungan untuk ini di Mojo ini misalnya: graphviz-maven-plugin.bryon.us/dot-mojo.html . Semua yang lain juga baru saja mendapat dukungan untuk file .dot.
oligofren

2

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.


Wow itu ... mengesankan. Saya sebenarnya punya beberapa komentar gaya diagram ASCII dalam kode saya. Terlalu memakan waktu. Saya ingin menggunakan alat yang lebih baik karena teknologinya sudah ada di sini. Saya dulu sering menulis kode di Vim tetapi skrip kesadaran kode apa yang saya gagal dibandingkan dengan IDE asli. Tapi terima kasih sudah menunjukkan teknik jadul ini padaku!
Steven Lu

Mengunjungi beberapa tahun kemudian dan sejak itu saya mengumpulkan beberapa barang Vim untuk membantu merakit diagram kotak dengan cepat. apakah itu ascii atau karakter kotak unicode, ini adalah cara yang sangat keren untuk memperindah beberapa kode dengan komentar keren dan berguna. Vim tidak datang dengan semua itu di luar kotak.
Steven Lu

1

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:

masukkan deskripsi gambar di sini

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

masukkan deskripsi gambar di sini

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!!!


1
Gambar-gambar yang luar biasa dan terima kasih untuk luncurannya (meskipun mungkin lebih banyak komentar daripada jawaban)! Saya baru-baru ini memutuskan untuk sepenuhnya berhenti dari grafik keren dan hal-hal simulasi dan membangun alat debugging dan penelusuran gen berikutnya . Apa yang Anda impikan sangat mirip dengan hal-hal yang saya impikan ....
Steven Lu

1
@ SevenLu Saya sering bermimpi membuat jenis IDE yang Anda usulkan dengan visual debugger (meskipun saya berpikir untuk melakukannya dari bawah karena saya tidak bisa membayangkan solusi plugin melakukan sisi debugger dengan sangat baik). Tapi ya - saya kira jawaban itu semacam komentar ... tapi saya sangat senang melihat orang lain berharap untuk itu. Rekan kerja saya di masa lalu lebih banyak tipe teknologi dan matematika - mereka tidak begitu mengerti keinginan saya untuk mengkomunikasikan semuanya secara visual.

1
Mungkin salah satu cara pseudo-ilmiah untuk melihatnya adalah bahwa sistem visual jauh dan jauh dari antarmuka bandwidth tertinggi yang kita miliki sebagai manusia, dan meskipun itu menyebalkan bahwa kita hanya memilikinya tersedia untuk digunakan sebagai input, integrasi dalam sistem visual ke dalam akses memori otak memungkinkan format visual keuntungan nyata untuk dokumentasi dan penyebaran konsep-konsep abstrak. ... Untuk itu, saya sedang mengerjakan alat IDE-agnostik (mengikuti filosofi Unix) yang memungkinkan aplikasi yang dikompilasi untuk secara otomatis menghasilkan representasi visual terstruktur dari internal sehingga kita dapat memahaminya.
Steven Lu

0

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


Mengapa downvote?
Reinstate Monica - M. Schröder

Saya membesarkan hati Anda. Ini pengamatan yang sangat bagus, apa yang saya diskusikan hampir seluruhnya jatuh di bawah payung itu.
Steven Lu

1
Saya downvoted juga karena ini tidak benar-benar memberikan jawaban. Dia jelas tidak ingin mengalihkan seluruh programnya ke gaya pemrograman melek huruf, dan bahkan jika dia melakukannya, pemrograman melek huruf hanyalah sebuah pendekatan untuk pemrograman - itu tidak berarti bahwa diagram dan gambar didukung.
Timmmm

0

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)

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.