1.7 Довідкова система

В Python визначено безліч функцій, що дозволяють вирішувати різні завдання. Деякі з них згруповані за призначенням і винесені в окремі модулі. Як визначати, для чого призначена та або інша функція, оскільки часто досить важко здогадатися про призначення функцій по їх назві.

Для спрощення роботи програміста в Python передбачена вбудована змінна __doc__ (починається і закінчується парами символів підкреслення), у якій зазвичай зберігається мінімальна довідкова інформація:

>>> print str.__doc__

str(object)-> string

Return а nice string representation of the object.

If the argument is а string, the return value is the same object.

>>>

Функція str() «представилася» і вивела інформацію про себе: які параметри вона приймає, якого типу значення повертає, і коротко «розповіла», що вона робить.

Починаючи з версії 2.2, в Python з'явилася довідкова система, реалізована у вигляді функції help(). Дана функція як параметр приймає ім'я будь-якого об'єкту (зокрема, модуля або функції) і виводить довідкову інформацію про нього.

>>> help(tuple)

Help on class tuple in module __builtin__:

class tuple(object)

| tuple() -> an empty tuple

| tuple(sequence) -> tuple initialized from sequence's items

|

| If the argument is a tuple, the return value is the same object.

|

| Methods defined here:

|

| __add__(...)

| x.__add__(y) <==> x+y

|

| __contains__(...)

| x.__contains__(y) <==> y in x

|

| __eq__(...)

| x.__eq__(y) <==> x==y

|

……………..

| index(...)

| T.index(value, [start, [stop]]) -> integer -- return first index of value.

| Raises ValueError if the value is not present.

|

| ----------------------------------------------------------------------

| Data and other attributes defined here:

|

| __new__ = <built-in method __new__ of type object at 0x1E1CC678>

| T.__new__(S, ...) -> a new object with type S, a subtype of T

Вихід з довідкової системи здійснюється клавішею [Q].

1.7. Коментарі в програмах

У міру збільшення розмірів ваших програм рано чи пізно ви зіткнетеся з однією проблемою: їх стане складніше читати. У ідеалі програма повинна читатися так само легко, неначебто вона була написана на природній мові. Тому для підвищення зрозумілості коду, його корисно забезпечувати коментарями на природній мові.

Коли над програмою працює один програміст, то відсутність коментарів компенсується хорошим знанням коду, але при роботі в команді, за рідкісними виключеннями, коментарі просто необхідні. Крім того, через якийсь час важко розібратися в своїй програмі, якщо в ній не буде додаткових зауважень.

В Python коментарі позначаються символом # – рядки, що починаються з цього символу, просто ігноруються інтерпретатором і ніяк не впливають на її трансляцію і виконання. Не допускається використання перед символом # лапок:

>>> а = “Це рядок” #Це коментар

>>> b = “#Це вже НЕ коментар”

Крім того, коментарями варто забезпечувати і функції. Для цього передбачений ще один спосіб багаторядкового коментування, воно починається і  закінчується трьома подвійними лапками ”””

def printTwice(value):

"""Описание функції printTwice()

Дана функція набуває значення і виводить його двічі, розділивши пропуском."""

print value, value

Як бачите, коментарі з описом функцій повинні знаходитися відразу після заголовка функції. Вони полягають з подвійні лапки три рази і можуть займати декілька рядків. Більш того, в Python передбачена можливість виведення цих коментарів. Для цього досить скористатися вбудованою змінною __doc__ (починається і закінчується парами символів підкреслення):

>>> print printTwice.__doc__

Опис функції printTwice()

Дана функція набуває значення і виводить його двічі, розділивши пропуском.

Цей же коментар виведе команда довідкової системи Python help(printTwice).

Вивчайте описи вбудованих функцій і при написанні своїх функцій прагніть коментувати їх в тому ж стилі, щоб іншим програмістам було простіше зорієнтуватися – до такої структури вже всі звикли.