Problem
Programiści piszą więcej tekstu niż większość ludzi zdaje sobie sprawę. Poza samym kodem, istnieje stały strumień pisania innego niż kod, który happens wewnątrz VS Code: komentarze wbudowane, ciągi definicji funkcji, sekcje README, robocze wersje wiadomości commitu, opisy biletów, adnotacje todo i notatki architektonicznych decyzji.
To pisanie jest często traktowane jako drugoplanowe — coś do zrobienia szybko, lub odrocz na później. Wynikiem jest bazy kodów z rzadką dokumentacją, funkcje bez wyjaśnienia, dlaczego istnieją, i decyzje architektoniczne, które istnieją tylko w czyjejś pamięci.
Tarcie jest rzeczywiste. Po spędzeniu energii mentalnej na złożonym algorytmie, ostatnią rzeczą, którą większość programistów chce robić, jest pisanie akapitu wyjaśniającego go. Pisanie czuje się jak dodatkowa praca na górze rzeczywistej pracy. Ale dokumentacja napisana natychmiast po wdrożeniu — gdy kontekst jest świeży — jest dramatycznie bardziej wartościowa niż dokumentacja napisana tydzień później, lub nigdy.
Jak Telvr pracuje z VS Code
Telvr integruje się z VS Code i każdym innym edytorem tekstu poprzez wstawianie tekstu na poziomie systemu na pozycji kursora. Nie jest wymagane żadne rozszerzenie VS Code. Nie ma klucza API w Twoim edytorze. Nie ma konfiguracji wewnątrz samego VS Code.
Przepływ pracy do dokumentacji programistycznej:
- Otwórz VS Code i umieść kursor w miejscu, gdzie chcesz, aby dokumentacja się pojawiła — powyżej funkcji, w bloku komentarza, w pliku README, lub w nowym dokumencie markdown.
- Naciśnij klawisz skrótu Telvr.
- Mów swoją dokumentację, wyjaśnienie lub opis zadania.
- Zwolnij klawisz. Sformatowane wyjście pojawi się na Twoim kursorze w mniej niż dwie sekundy.
- Kontynuuj kodowanie.
Telvr pracuje we wszystkich kontekstach VS Code: samym edytorze, zintegrowanym terminalu (dla mówionych pomysłów poleceń) i plikach podglądu markdown. Działa również w pliku JSON ustawień VS Code i innych plikach konfiguracyjnych, w których możesz chcieć dodać komentarze.
Najlepszy tryb wzbogacania do VS Code: Dev Task
Tryb Dev Task jest zaprojektowany specjalnie do dokumentacji przepływu pracy programistycznej. Kiedy aktywujesz go i mówisz o kawałku kodu lub zadaniu, AI ustrukturyzuje Twoje wyjście w format gotowy do programowania z czterema sekcjami:
Kontekst: Informacje tła wyjaśniające, co ten kod robi, dlaczego istnieje, lub jaki problem rozwiązuje.
Wymagania: Co musi być spełnione w wdrożeniu — ograniczenia, zależności, przypadki graniczne, lub zasady biznesowe.
Uwagi dotyczące wdrożenia: Szczegóły techniczne, zastosowany podход, rozpatrywane kompromisy, lub ważne zastrzeżenia.
Kryteria akceptacji: Jak sprawdzić, czy wdrożenie jest poprawne — jakie testy powinny przejść, jakie zachowanie oczekiwać, lub jakie warunki określają sukces.
Ta struktura jest natychmiast użyteczna dla:
- Bloków dokumentacji na poziomie funkcji wyjaśniających złożoną logikę
- Komentarzy nagłówka na poziomie pliku dla niejasnych modułów
- Opisów zadań podczas planowania pracy bezpośrednio w plikach kodu
- Rekordów architektonicznych decyzji (ADR) przygotowanych w markdown
Do prostszych komentarzy wbudowanych — szybkie wyjaśnienie wyrażenia regularnego, notatka o znanym ograniczeniu — tryb Czystości i poprawności daje czysty, czytelny tekst bez formalnej struktury.
Przykład przed i po
Surowe wejście głosowe (tryb Dev Task):
"więc ta funkcja obsługuje ograniczanie szybkości dla API uh musi śledzić żądania na użytkownika na minutę i powinno używać okna przesuwającego się nie okna stałego, ponieważ stałe okna mogą pozwolić na traffic burst zaraz na granicy um zależy od Redis dla magazynu licznika i powinny zwrócić 429 z nagłówkiem retry-after gdy limit zostanie przekroczony powinniśmy również upewnić się, że klucze limitu automatycznie się wygasają, abyśmy nie wypełnili Redis w czasie"
Po trybie Dev Task:
Kontekst Obsługuje ograniczanie szybkości API na użytkownika za pomocą algorytmu okna przesuwającego. Używa Redis dla rozproszonych magazynów licznika do obsługi wdrożeń wieloinstancyjnych.
Wymagania
- Śledzenie żądań na użytkownika na minutę za pomocą okna przesuwającego (nie okna stałego)
- Zwrot HTTP 429 z nagłówkiem
Retry-Aftergdy limit zostanie przekroczony- Klucze Redis muszą automatycznie wygasnąć, aby zapobiec nieograniczonemu wzrostowi magazynu
Uwagi dotyczące wdrożenia
- Okno przesuwające wybrane nad oknem stałym, aby zapobiec traffic burst na granicach okna
- Redis zależy od rozproszonego stanu limitu szybkości
Kryteria akceptacji
- Limit szybkości jest wymuszany poprawnie pod wzorem nacisku i traffic burst
- Klucze Redis wygasają zgodnie z oczekiwaniem (weryfikuj poleceniami TTL)
- Odpowiedzi 429 zawierają prawidłowy nagłówek
Retry-After- Brak akumulacji klucza Redis po rozszerzonych okresach testowych
Mówiona wersja to rozmowita wyjaśnienie. Wyjście Dev Task to ustrukturyzowana specyfikacja, którą możesz wkleić bezpośrednio powyżej funkcji jako blok dokumentacji.
Oszczędności czasu
Dokumentacja jest chronicz niedociniana, ponieważ jest wolna do pisania w stosunku do jej postrzeganej wartości w chwili. Programiści, którzy przełączają się na dokumentację głosową, raportują dwie zmiany: dokumentują więcej i dokumentują lepiej.
Pisanie gruntownego bloku dokumentacji funkcji zajmuje pięć do osiem minut skoncentrowanego pisania. Mówienie tej samej zawartości zajmuje sześćdziesiąt do dziewięćdziesięciu sekund, a tryb Dev Task obsługuje formatowanie. Zmniejszony inwestycję czasu sprawia, że dokumentacja czuje się żywotna, a nie uciążliwa.
Do dłuższych dokumentów — README, rekordów architektonicznych decyzji, przewodników wdrażania — oszczędności czasu są proporcjonalne. README pięciuset słów, który zajęłby czterdzieści pięć minut na pisanie, może być dyktowany w dziesięciu do dwunastu minut, a następnie edytowany stamtąd.
Jest również argument jakości. Kiedy dokumentacja jest przygotowywana natychmiast po napisaniu kodu, podczas gdy szczegóły wdrożenia są świeże, wynikająca dokumentacja jest bardziej dokładna i bardziej użyteczna. Szybkość Telvr sprawia, że praktyczne jest dokumentowanie podczas kodowania, a nie jako odroczonym zadaniem.
W typowym tygodniu programistycznym z regularną pracą dokumentacyjną, Telvr może odzyskać dwie do trzech godzin — i dać działającą, lepiej udokumentowaną bazę kodu w rezultacie.
Rozpoczęcie pracy
- Pobierz Telvr dla macOS z telvr.ai.
- Ukończ konfigurację i skonfiguruj preferowany mikrofon.
- Ustaw klawisz skrótu, który działa w Twoim przepływie pracy VS Code — coś, co możesz nacisnąć bez przesuwania rąk daleko od głównego rzędu.
- Otwórz VS Code, umieść kursor powyżej funkcji lub w bloku dokumentacji i przetestuj swoją pierwszą dyktację.
- Ustaw Dev Task jako domyślny tryb dla pracy dokumentacji programistycznej.
Dobre pierwsze ćwiczenie: znajdź trzy najbardziej złożone funkcje w swoim aktualnym projekcie — te, które czerpieć korzyść ze składki dokumentacji — i dyktuj blok Dev Task dla każdej. Całe ćwiczenie powinno zająć poniżej dziesięciu minut i dać dokumentację, która zajęłaby godzinę do napisania.
Telvr zawiera 14-dniową bezpłatną próbę z pełnym dostępem do wszystkich trybów wzbogacania. Po próbie, ceny wynoszą 3 EUR miesięcznie plus 0,03 EUR za minutę transkrypcji.