Adnotuj kod źródłowy za pomocą diagramów jako komentarzy

Piszę dużo kodu (głównie c ++ i javascript), który dotyczy geometrii obliczeniowej i grafiki oraz tego rodzaju tematów, więc odkryłem, że diagramy wizualne są nieodzowną częścią procesu rozwiązywania problemów.

Właśnie ustaliłem, że „och, czy nie byłoby po prostu fantastycznie, gdybym mógł jakoś dołączyć ręcznie rysowany diagram do fragmentu kodu jako komentarz”, a to pozwoliłoby mi wrócić do czegoś, nad czym pracowałem, dni, tygodnie, miesiące wcześniej i znacznie szybciej odtwarzają moje algorytmy.

Jako wizualny uczeń uważam, że może to poprawić moją produktywność z prawie każdym rodzajem programowania, ponieważ proste diagramy mogą pomóc w zrozumieniu i uzasadnieniu każdego rodzaju nietrywialnej struktury danych. Na przykład wykresy. Podczas zajęć z teorii grafów na uniwersytecie byłem w stanie naprawdę dobrze zrozumieć relacje wykresów, z których w rzeczywistości mogłem narysować schematyczne przedstawienia.

Więc...

Według mojej wiedzy, żadne IDE nie pozwala na zapisanie zdjęcia jako komentarza do kodu.

Myślałem, że ja lub ktoś inny może wymyślić jakieś dość łatwe w użyciu narzędzie, które może przekonwertować obraz na ciąg binarny base64, który następnie mogę wstawić do mojego kodu.

Jeśli proces konwersji / wstawiania może być wystarczająco usprawniony, umożliwiłoby to znacznie lepsze połączenie między diagramem a rzeczywistym kodem, więc nie muszę już chronograficznie przeszukiwać moich notatników. Jeszcze bardziej niesamowite: wtyczki dla IDE do automatycznego analizowania i wyświetlania obrazu. Z teoretycznego punktu widzenia nie ma w tym absolutnie nic trudnego.

Domyślam się, że zajęłoby mi to trochę więcej czasu, aby dowiedzieć się, jak rozszerzyć moje ulubione IDE i utrzymać te wtyczki, więc byłbym całkowicie zadowolony z rodzaju postprocesora kodu, który wykonałby to samo parsowanie i renderowanie obrazów i pokazywanie ich obok kodu, w przeglądarce lub coś takiego. Ponieważ z zawodu jestem programistą javascript.

Co ludzie myślą? Czy ktoś za to zapłaci? Ja bym. Być może jednak chciałbym również zauważyć, że niezależnie od tego, czy ja lub jakaś znacząca liczba moich rówieśników zapłaciłaby za coś takiego, jedynym sposobem na osiągnięcie sukcesu może być wydanie open source.

Co z wtyczką wstawiania obrazu dla programu Visual Studio ?

Jeśli używasz innego IDE i albo nie obsługuje on osadzonych obrazów, albo nie masz czasu na jego rozszerzenie, to co z umieszczeniem linku do obrazu w komentarzach, podczas gdy obraz będzie znajdować się gdzieś w repozytorium ?

Jeśli nie jesteś artystą ASCII , możesz użyć doxygen jako narzędzia dokumentacji wraz z zintegrowaną z nim aplikacją dot / graphviz .

Umożliwia to pisanie tekstowego opisu wykresów i renderowanie ich w dokumentacji.

Na przykład ten opis:

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

renderuje jako:

Możesz wypróbować tryb artysty emacsa. Robiłby sztukę ascii zamiast obrazów jako takich, więc może, ale nie musi być tym, czego szukasz. W szczególności, jeśli twoje IDE nie robi czcionek o stałej szerokości, nie byłoby to przydatne. Będąc zwykłym tekstem, grałaby bardzo ładnie z kontrolą wersji.

Oto zrzut ekranu z trybu artysty, dzięki czemu możesz dowiedzieć się, czy jesteś zainteresowany, czy nie.

Aby uruchomić tryb artysty w emacsie, wykonaj Alt-x, wpisz tryb artysty i naciśnij klawisz Return. Środkowy przycisk myszy wyświetla menu. Skróty klawiszowe do wycinania i wklejania nie są domyślnie normalnymi oknami, ale możesz włączyć tryb CUA, aby to zmienić.

Co ludzie myślą? Czy ktoś za to zapłaci? Ja bym.

ZOMG, pasuję do podobnej kategorii jak ty i chciałbym taką funkcję bezpośrednio w IDE.

Na razie robię tak dużo „sztuki” ASCII jak to:

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

Główną wartością, którą znajduję, jest widzenie nazw zmiennych odpowiadających diagramowi wizualnemu, szczególnie gdy używamy złożonych przejść siatek i takich dla nowych algorytmów siatki. Ta sztuczka generowania wykresów doksygenowych pokazana w jednej z odpowiedzi jest super fajna - powinienem spróbować jeszcze więcej.

Jest tak wiele rzeczy, które są łatwiejsze do komunikowania się również wizualnie, niekoniecznie nawet przy użyciu grafów. Przykład:

... lub to (porównanie mojego algorytmu nazywam „podpisem hakowym” do standardowego podziału CC używanego przez Pixar):

Dałoby to kodowi tak dużo kontekstu, aby zobaczyć, co robią te operacje i jak różnią się one w kodzie, ponieważ niektóre rzeczy najlepiej pokazać wizualnie. Zdjęcia naprawdę potrafią uchwycić tysiąc słów.

Byłoby więc dla mnie całkowicie senne mieć IDE, które pozwala mi widzieć kod i obrazy obok siebie, co pozwala mi osadzać obrazy w kodzie źródłowym.

Zwłaszcza, gdy wymyślamy nowe algorytmy, trudno jest znaleźć dobry sposób, aby opisać je bardzo dokładnie (z technicznego punktu widzenia, a nie dokładnie z perspektywy użytkownika) bez wchodzenia w etapy algorytmiczne, ponieważ nie ma nic, z czym można by je bezpośrednio porównać. Tego rodzaju obrazy przed i po zwykle pokazują od razu, czego można oczekiwać od algorytmu.

Kolejną rzeczą, o której marzę, jest wizualny debugger, który pozwala mi go zaprogramować, dzięki czemu niektóre moje typy danych mogą wyświetlać obraz w debuggerze, np. Aby zobaczyć wyniki wizualnie, gdy przeglądam kod i sprawdzam algorytmy Próbuję wymyślić, działają poprawnie na każdym kroku i pasują do tego, jak narysowałem to na papierze. Na przykład spraw, aby moja struktura danych siatki wyświetlała renderowany obraz w oknie obserwacyjnym debugera - idealnie, gdybym mogła nawet obrócić widok i tak tam i teraz.

Również podczas pracy w bardzo dużych bazach kodu (dziesiątki milionów LOC) napisanych przez luźne zespoły z tysiącem wtyczek, czasem może być koszmar po prostu dowiedzieć się, jak wykonać kod, który jest dla nas niejasny, rzadko używana wtyczka z interfejsu użytkownika. Byłoby tak niesamowicie w tych przypadkach, gdyby kod mógł osadzić miniaturowy zrzut ekranu pokazujący, jak faktycznie wywołać ten kod z interfejsu użytkownika (może być podatny na od czasu do czasu nieaktualne, ale zwykle interfejsy użytkownika nie są tak niestabilne w poprzek wersje, aby poprzednie ekrany były bezużyteczne).

Czy ktoś za to zapłaci? Ja bym.

W każdym razie tak, całkowicie! Chcę tego!!!

Brzmi jak przypadek użycia programowania literackiego, w którym można dodawać diagramy i cokolwiek do dokumentacji.

Doxygen pozwala wstawiać obrazy w komentarzach takich jak to:

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

Niestety wydaje się, że żadne IDE nie będą wyświetlać tych obrazów bezpośrednio, ale podejrzewam, że napisanie rozszerzenia VSCode nie byłoby zbyt trudne, aby to zrobić na przykład.

Znalazłem również jedno rozszerzenie VSCode, które już obsługuje to z innym komentarzem składniowym . Odbywa się to poprzez najechanie myszką:

VSCode dodaje funkcję, która pozwala na wstawianie obrazów - „wstawka kodu” - ale nie wydaje się jeszcze gotowa.

Oto zrzut ekranu z przykładowego rozszerzenia (którego nie udało mi się znaleźć - prawdopodobnie nie zostało jeszcze wydane, ponieważ wstawiony kod API nie został jeszcze wydany)