Python docstring & annotations | metadata __doc__ & __annnotations__ | docstring styles
Docstring (Sənədləşmə Sətirləri)
Nə Üçündür?
• Koddakı funksiyanın, sinifin və ya modulun nə etdiyini izah edir.
• Kodu oxuyanlar üçün aydınlıq yaradır, xüsusilə komanda ilə işləyərkən və ya böyük layihələrdə.
• Kodun saxlanması, başa düşülməsi və yenilənməsi üçün çox faydalıdır.
Harada İstifadə Olunur?
• Funksiya, class(sinif), modul və ya skriptin ən başında yerləşir.
• Funksiyanın məqsədini, qəbul etdiyi dəyərləri, qaytardığı nəticəni və xüsusi halları izah edir.
Quruluşu və Qaydaları:
• Adətən qısa bir təsvirlə başlayır.
• İstəyə görə bölmələr əlavə olunur: Parametrlər, Qaytardığı dəyər, Xətalar, Nümunələr.
• Müxtəlif standart stillər var (məsələn: Google stili, NumPy stili və s.).
Nəyə Görə Vacibdir?
• Avtomatik sənədləşmə vasitələri (məsələn, Sphinx) docstring-ləri istifadə edir.
• Kod redaktorları və IDE-lər docstring-ləri avtomatik olaraq göstərə bilir.
• Yeni proqramçılar və ya komanda üzvləri üçün çox faydalıdır.
⸻
Annotation-lar (Tip Göstərişləri)
Nə Üçündür?
• Funksiyaların gözlədiyi və qaytardığı məlumat tiplərini göstərir.
• Kodun daha aydın və oxunaqlı olmasına kömək edir.
Əsas Üstünlükləri:
• Kodun məntiqini başa düşmək asanlaşır, xüsusilə mürəkkəb və ya uzun kodlarda.
• Statik analiz alətləri (məsələn, mypy) potensial səhvləri aşkar edə bilər.
• Kod redaktorları daha dəqiq avtomatik tamamlamalar təklif edir.
• Proqramlaşdırma vərdişlərini yaxşılaşdırır, səhvləri azaldır.
Necə İstifadə Olunur?
• Funksiya parametrlərinə və qaytardığı nəticəyə tip göstərişi əlavə olunur.
• Dəyişənlərə də tip göstərmək mümkündür (məsələn, ədəd, sətr, siyahı və s.).
Diqqətəlayiq Nöqtələr:
• Python dinamik tipli dildir — yəni bu göstərişlər icra zamanı məcburi deyil.
• Annotation-lar seçimlidir, lakin tövsiyə olunur.
• Mürəkkəb tiplərlə də işləyə bilər (məsələn: siyahıların içində ədədlər, fərqli tiplərin birləşməsi və s.).
=======
Docstrings (Documentation Strings)
Purpose:
• Help describe what your code is doing.
• Act as in-line documentation for anyone reading or using the code.
• Make your code easier to understand and maintain.
Where They Are Used:
• Inside functions, classes, modules, and even at the start of a script.
• They should explain the purpose, inputs, outputs, and any important behavior or edge cases.
Structure & Conventions:
• Usually start with a short description of what the object does.
• Can include sections like Parameters, Returns, Raises, and Examples.
• There are popular styles such as Google, NumPy, and reStructuredText (RST) that help keep docstrings consistent.
Why They Matter:
• Tools like documentation generators (e.g., Sphinx) use docstrings to create external documentation.
• IDEs and help systems can show docstrings when hovering over functions or using autocomplete.
• Great for teaching, onboarding new developers, and debugging.
⸻
Annotations (Type Hints)
Purpose:
• Indicate what kind of data is expected or returned in functions and variables.
• Add clarity to the code, especially in complex or collaborative projects.
Key Benefits:
• Make code more self-explanatory without needing to run it.
• Help static analysis tools detect bugs early (e.g., type mismatches).
• Improve auto-completion and intelligent suggestions in IDEs.
• Encourage better programming practices and reduce errors.
How They’re Used:
• You can annotate both function arguments and return types.
• Also used with variables to indicate their intended type.
Important Notes:
• Python is still dynamically typed — annotations are not enforced during execution.
• They’re optional, but highly recommended in large or shared codebases.
• You can use complex types like lists of specific items, custom classes, or even unions of types.
#python #kody_az #kodyaz #viral #fleet #jetbrains #pycharm #oop #viralcode #viralvideo #random #code #coder #azerbaycan #azerbaijan #azərbaycan #baku #baki #programming #programmer #codes #hazırlıq #hazirliq #kurs #kurslar #course #courses #online #onlinecourses #test #quiz
On this page of the site you can watch the video online Python docstring & annotations | metadata __doc__ & __annnotations__ | docstring styles with a duration of hours minute second in good quality, which was uploaded by the user KODY•AZ 01 April 2025, share the link with friends and acquaintances, this video has already been watched 85 times on youtube and it was liked by 15 viewers. Enjoy your viewing!
