Napisz docstring dla wskazanej funkcji [wklej funkcję poniżej] - Prompt do ChatGPT
Generuj zgodne z PEP 257 docstringi (Google/NumPy/Sphinx) z parametrami, zwrotami, wyjątkami i przykładami, z automatyczną analizą kodu, oszczędzając czas.
Co robi ten prompt
Generuje profesjonalną dokumentację (tzw. docstring) dla dostarczonego kodu funkcji, co znacząco ułatwia zrozumienie jego działania. Strukturuje wygenerowaną dokumentację zgodnie z najlepszymi praktykami, dzieląc ją na sekcje takie jak podsumowanie, argumenty, zwracane wartości i przykłady użycia. Umożliwia dostosowanie stylu dokumentacji do konkretnego języka programowania oraz popularnych standardów (np. Google, NumPy, Javadoc), zapewniając spójność w projekcie.
Wskazówki
Aby uzyskać najdokładniejszy wynik, podaj kompletny kod funkcji, włącznie z sygnaturą i (jeśli język na to pozwala) adnotacjami typów. Im więcej kontekstu ma model, tym precyzyjniejsza będzie dokumentacja. Jeśli logika funkcji jest złożona, nieoczywista lub dotyczy specyficznej domeny biznesowej, rozważ dodanie krótkiego komentarza w prompcie wyjaśniającego jej główny cel. Pomoże to w stworzeniu bardziej trafnego opisu.
Jesteś doświadczonym programistą specjalizującym się w pisaniu czystego, czytelnego i doskonale udokumentowanego kodu zgodnie z zasadami "Clean Code". Twoim celem jest tworzenie dokumentacji (docstring), która jest precyzyjna, zwięzła i natychmiastowo zrozumiała dla innych deweloperów.
Przeanalizuj podany kod funkcji i wygeneruj dla niej profesjonalny, kompletny docstring. Zastosuj najlepsze praktyki dokumentacji kodu dla wskazanego języka programowania i, jeśli został podany, wybranego standardu.
Twój docstring musi być gotowy do wklejenia bezpośrednio do kodu i powinien zawierać następujące, jasno oddzielone sekcje:
- Podsumowanie: Jedno, zwięzłe zdanie opisujące główny cel i działanie funkcji.
- Argumenty/Parametry: Lista wszystkich argumentów przyjmowanych przez funkcję. Dla każdego argumentu podaj:
nazwa (typ): Krótki, ale precyzyjny opis przeznaczenia.
- Zwraca (Returns): Jasny opis wartości zwracanej przez funkcję, włączając w to jej typ danych.
- Wyjątki (Raises/Throws): (Jeśli dotyczy) Lista potencjalnych wyjątków, które mogą zostać zgłoszone, wraz z opisem warunków, które je powodują.
- Przykład użycia (Example): Prosty, działający fragment kodu demonstrujący, jak prawidłowo wywołać funkcję i co można uzyskać w wyniku.
- Precyzja i Zgodność: Docstring musi być w 100% zgodny z sygnaturą i logiką działania funkcji. Skup się na dokładnym opisaniu typów danych i warunków brzegowych.
- Praktyczność: Sekcja "Przykład użycia" jest kluczowa. Musi być poprawna składniowo i jednoznacznie pokazywać praktyczne zastosowanie funkcji.
- Zwięzłość: Opisuj "co" robi funkcja i "dlaczego", a nie "jak" to robi – implementacja jest widoczna w kodzie. Unikaj oczywistych i redundantnych informacji.
Jak używać tego prompta
Należy uzupełnić pola [Język programowania], [Kod funkcji] oraz opcjonalnie [Standard dokumentacji]. Przykładowo, dla funkcji obliczającej średnią w Pythonie, dane mogą wyglądać następująco: Język programowania: Python, Kod funkcji: def oblicz_srednia(liczby): if not liczby: raise ValueError('Lista nie może być pusta'); return sum(liczby) / len(liczby), Standard dokumentacji: Google.
Dobrze wiedzieć
Dobrze napisana dokumentacja jest fundamentem utrzymywalnego i skalowalnego oprogramowania. Ułatwia współpracę w zespole, przyspiesza wdrażanie nowych programistów i redukuje czas potrzebny na zrozumienie istniejącego kodu. Używanie tego prompta do automatyzacji tworzenia spójnych i kompletnych docstringów pomaga w utrzymaniu wysokiej jakości projektu i promuje kulturę 'Clean Code'. Należy pamiętać, że chociaż model AI doskonale radzi sobie z analizą składni i bezpośredniej logiki kodu, może nie wychwycić subtelnego kontekstu biznesowego lub niuansów specyficznych dla danego projektu. Dlatego wygenerowany docstring powinien być zawsze zweryfikowany przez dewelopera, aby upewnić się, że w pełni oddaje intencję i rolę funkcji w całym systemie. Taka weryfikacja gwarantuje, że dokumentacja jest nie tylko technicznie poprawna, ale również użyteczna kontekstowo.