База для программиста, часть 6: как читать документацию и разбираться в чужом коде

База для программиста, часть 6: как читать документацию и разбираться в чужом коде

Читать документацию и чужой код — отдельный навык, и ему почти не учат на курсах напрямую. Курс показывает, как решить конкретную задачу, а в работе вы чаще сталкиваетесь с незнакомой библиотекой, непонятной ошибкой или проектом, который написал не вы. Ниже разберём, как устроена документация, как быстро находить в ней нужное, как читать сообщения об ошибках и как подступаться к чужому проекту. Все примеры запущены в реальном терминале, вывод взят из настоящих запусков.

Это шестая часть серии «База для программиста». В части 5 мы разобрали алгоритмы и структуры данных. Здесь продолжаем на Python, но приёмы подходят для любого языка.

Почему это отдельный навык

Выучить синтаксис можно за несколько недель. Но реальная работа выглядит иначе:

• нужно подключить библиотеку, которую вы раньше не видели;
• вы получаете проект от коллеги, и в нём десятки файлов;
• программа падает с ошибкой, которую вы не понимаете.

Во всех трёх случаях помогает не знание ещё одной функции, а умение быстро найти ответ в источнике. Разработчик, который умеет читать документацию, обгоняет того, кто знает больше, но всё ищет вслепую.

Из чего состоит документация

Хорошая документация обычно делится на несколько частей, и важно понимать, чем они отличаются:

• Руководство для начинающих (Getting started, Tutorial). Ведёт от установки до первого примера. Читайте первым, когда знакомитесь с инструментом.
• Практические рецепты (How-to). Ответы на вопросы вида «как сделать X». Удобны, когда задача ясна.
• Справочник (Reference, API). Подробное описание каждой функции и параметра. Читают не подряд, а ищут нужное место.
• Объяснения (Concepts, FAQ). Почему инструмент устроен именно так.
• История изменений (Changelog). Что поменялось в новых версиях. Пригодится, если код из интернета «внезапно перестал работать».

Типичная ошибка новичка — читать документацию подряд, с начала до конца. Правильнее выбрать нужный тип: для знакомства руководство, для конкретной функции справочник.

Справка прямо в терминале

Не всегда нужно открывать сайт: многие программы объясняют себя сами. Вот самый быстрый способ.

Флаг --help у программ. Ответ сразу в терминале:

ls --help

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

Mandatory arguments to long options are mandatory for short options too.
  -a, --all                  do not ignore entries starting with .
  -A, --almost-all           do not list implied . and ..
      --author               with -l, print the author of each file

Первая строка (Usage) показывает шаблон вызова: что обязательно, что нет. В квадратных скобках то, что можно не указывать. Ниже перечислены параметры.

Краткая справка у Git. У большинства команд есть короткий вариант -h:

git switch -h

usage: git switch [<options>] [<branch>]

    -c, --[no-]create <branch>
                          create and switch to a new branch
    -C, --[no-]force-create <branch>
                          create/reset and switch to a branch

Читается так же: что делает флаг -c, видно сразу, без поиска в интернете.

Справка Python. Встроенная функция help() показывает описание прямо из кода:

help(str.split)

Как читать описание функции

Возьмём справку по методу str.split и разберём по частям. Это настоящий вывод Python 3.12.

Что здесь важно:

1. Сигнатура: split(self, /, sep=None, maxsplit=-1). Слово self и символ / пока можно пропустить. Главное: у функции два необязательных параметра, оба имеют значения по умолчанию. Значит, text.split() вызвать можно без аргументов.
2. Что делает: возвращает список подстрок. Вы сразу знаете тип результата.
3. Параметры: для каждого указано, что он значит и что происходит, если не задавать его (по умолчанию разделение идёт по любым пробельным символам, пустые строки отбрасываются).
4. Предупреждение: внизу справки сказано, что для обычного текста со знаками препинания лучше подойдут регулярные выражения. Эти абзацы часто пропускают, хотя именно в них прячутся ответы на вопрос «почему не работает».

Привычный порядок чтения справки: что принимает → что возвращает → значения по умолчанию → предупреждения и примеры.

Как искать ответ, когда не получается

Пошаговый порядок, который экономит часы:

1. Официальная документация. Начинайте с неё: она точнее всего и привязана к версии. Для Python это docs.python.org, для веба MDN, для других инструментов раздел Docs на их сайте.
2. Сообщение об ошибке целиком. Скопируйте последнюю строку ошибки и вставьте в поиск вместе с названием языка или библиотеки. Не обрезайте её и не заменяйте своими словами.
3. Обсуждения проектов и форумы. Раздел Issues на GitHub, вопросы на специализированных форумах и в профильных сообществах. Проверяйте дату ответа: решение трёхлетней давности может не подходить к новой версии.
4. Проверьте версию. Если пример из интернета не работает, сравните версию вашего инструмента с той, для которой он написан. Это одна из самых частых причин.
5. Попробуйте сами в маленьком эксперименте. Откройте интерактивную консоль и проверьте гипотезу на трёх строках, не запуская весь проект.

Как читать сообщение об ошибке

Ошибки пугают, но читать их можно по простому правилу: снизу вверх. Вот настоящая ошибка, которую выдал Python, когда в функцию вместо текста передали None:

Traceback (most recent call last):
  File "<string>", line 3, in <module>
  File "/home/anna/project/wordstat.py", line 7, in top_words
    words = re.findall(r"\w+", text.lower())
                               ^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'lower'

(Путь к файлу у вас будет свой.)

• Последняя строка говорит, что случилось: у значения None нет метода lower. То есть переменная text оказалась пустой, а мы вызвали метод строки.
• Строки выше показывают, где: файл wordstat.py, строка 7, функция top_words. Знаки ^^^^ указывают на конкретное место.
• Самые верхние строки — цепочка вызовов, которая привела к этому. На первом этапе она вам почти не нужна.

Почему вообще пришёл None, придётся выяснять отдельно: это уже отладка, и ей посвящена следующая часть серии.

Как разобраться в чужом проекте

Незнакомый код пугает объёмом. Работает один простой принцип: не читать всё подряд, а идти от общего к частному.

1. Сначала README. Что делает проект, как его установить и запустить. Если README нет или он пустой, это уже информация о проекте.
2. Структура папок. Откройте дерево файлов: где исходники, где тесты, где настройки. Названия папок обычно подсказывают, что где лежит.
3. Точка входа. Найдите, откуда запускается программа: файл main.py, index.js, блок if __name__ == "__main__":. От него и начинайте читать.
4. Тесты как документация. Хорошие тесты показывают, как функции вызывают и что должны возвращать. Часто понятнее самого кода.
5. Запустите и поменяйте. Запустите программу, затем измените что-то маленькое и посмотрите, как это повлияет на результат. Понимание приходит быстрее, чем при чтении.

Разбираем небольшой пример

Представим, что вам досталась такая функция, и вы не знаете, что она делает:

import re
from collections import Counter

STOP = {"и", "в", "на", "с", "не"}

def top_words(text, n=3):
    words = re.findall(r"\w+", text.lower())
    words = [w for w in words if w not in STOP]
    return Counter(words).most_common(n)

if __name__ == "__main__":
    sample = "Кот и пёс. Кот на диване, пёс не на диване. Кот спит."
    print(top_words(sample))

Идём по шагам.

1. Запустите и посмотрите результат.

[('кот', 3), ('пёс', 2), ('диване', 2)]

Уже ясно: функция возвращает самые частые слова и сколько раз каждое встретилось.

2. Разберите незнакомые части по порядку. re.findall(r"\w+", ...) вы видите впервые? Проверьте в консоли на крошечном примере:

import re
print(re.findall(r'\w+', 'Кот, пёс; кот!'))

['Кот', 'пёс', 'кот']

Теперь понятно: регулярное выражение вырезает слова и отбрасывает знаки препинания. Так вы заодно увидели, что text.lower() нужен, чтобы «Кот» и «кот» считались одним словом.

3. Проверьте крайние случаи. Что будет с пустой строкой? Что с параметром n?

from wordstat import top_words
print(top_words('а б а в а б', 2))
print(top_words('', 2))

[('а', 3), ('б', 2)]
[]

Пустая строка не ломает функцию, возвращается пустой список. А вот None вместо строки приведёт к той самой ошибке из предыдущего раздела.

4. Только теперь загляните в документацию по Counter.most_common, если остались вопросы.

Видите порядок: запустить → потрогать части в консоли → проверить граничные случаи → читать документацию. Он работает на любом коде, даже на большом.

Типичные ошибки новичков

• Читать документацию подряд. Берите нужный раздел: руководство для знакомства, справочник для поиска.
• Не читать сообщение об ошибке. Многие сразу копируют его в поиск, не вчитываясь. А ответ часто виден уже в последней строке.
• Искать ответы без учёта версии. Инструкция для старой версии может не подходить к вашей.
• Копировать чужой код, не понимая его. Он может работать сегодня и сломаться при первой же правке. Разберите каждую строку или хотя бы запустите по частям.
• Не пробовать запускать. Читать код глазами без запуска намного медленнее, чем изменить значение и посмотреть результат.
• Пропускать тесты и README. Это самые короткие пути к пониманию проекта.

Мини-упражнение

1. Откройте терминал и выполните ls --help (на macOS: man ls, на Windows в PowerShell: Get-Help ls). Найдите флаг для вывода подробной информации о файлах.
2. В Python выполните help(str.replace) и ответьте: какие у метода параметры, какие из них необязательные, что он возвращает.
3. Запустите функцию top_words из статьи. Измените список STOP и посмотрите, как поменяется результат.
4. Вызовите top_words(None). Прочитайте ошибку снизу вверх и объясните своими словами, что случилось и где.
5. Выберите любой небольшой открытый проект на GitHub (до десяти файлов), откройте README, найдите точку входа и опишите одним предложением, что он делает.

Что дальше

Умение читать ошибки — первый шаг, но найти причину бага и исправить её — отдельная работа. Об этом следующая часть серии: про отладку. <!-- добавить ссылку на часть 7 после публикации -->

Если вы выбираете курс по программированию, программы обучения собраны в каталоге MAXCOURSE. Все части серии доступны по тегу baza-programmista.

Частые вопросы

Почему документация кажется сложной?
Справочник написан для тех, кто уже понимает основы. Начинайте с руководства для начинающих и примеров, а справочник используйте как словарь, к которому обращаются по необходимости.

Нужно ли знать английский, чтобы читать документацию?
Помогает очень: большинство первоисточников и сообщений об ошибках на английском. Для старта хватает базовых слов и переводчика, словарь типичных терминов (return, parameter, argument, default, deprecated) запоминается быстро.

Что делать, если пример из интернета не работает?
Проверьте версию инструмента, прочитайте сообщение об ошибке целиком и сверьтесь с официальной документацией. Часто достаточно обновить библиотеку или заменить устаревшую функцию на новую.

Как быстро разобраться в большом чужом проекте?
Не читать всё подряд. Начните с README и структуры папок, найдите точку входа, запустите программу и меняйте небольшие части, наблюдая за результатом. Тесты, если они есть, показывают, как проект должен работать.

Можно ли использовать ИИ-помощников для разбора кода?
Можно, как дополнительный инструмент: попросить объяснить незнакомую функцию или ошибку. Но ответ стоит проверять в документации и на практике, потому что помощник может ошибаться или опираться на устаревшую версию.

Проверено: Python 3.12.3