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.
Rola i Kontekst: 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.
Zadanie (Cel): 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.
Format Odpowiedzi: 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.
Najważniejsze:
- 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.