json_encoded_data = b'{"foo": {"bar": ["buzz", "fizz"], "qwe": 123}}'
decoded_data = json.loads(json_encoded_data)

json_encoded_data — вот это JSON. decoded_data — а это не JSON.

Не надо называть большой дикт словом json. Это не JSON, это просто большой дикт, который может быть закодирован в XML, ASN.1, Protobuf, код на Python и кучу других форматов данных.

Называйте словом json байты или, на худой конец, строку, которая получена путем декодирования байтов из UTF-8.

Обычно у авторов опенсорс-проектов потребность и запал пропадают очень быстро, и когда проект становится востребованным, автору до него нет дела. В него вяло делают пулл-реквесты разработчики со стороны, и никто не обладает достаточным желанием и знанием кодовой базы, чтобы это все отрефакторить.

Что касается конкретно Питона, я вообще нигде не видел хорошего кода. (Кроме того, который пишет мой отдел, конечно.) И стандартная библиотека, и популярные библиотеки. Где-то бывает хороший интерфейс, какие-то очень хорошо помогают для очень стандартных задач, что-то очень хорошо кастомизируется. Но в целом все тухло.

Да и не бывает кода, хорошего для всех. Как и не бывает человека, который всем нравится. Тимлид должен понимать, что от конкретного компонента требовать, какого уровня качества и каких характеристик. Есть разные требования бизнеса, разные аудитории пользователей, разные этапы жизни проекта, разная квалификация разработчиков.

Когда правилом пренебрегают, фактически в правило добавляется оговорка о том, что им можно пренебрегать по своему усмотрению. Иногда такую оговорку добавляют формально, то есть пишут в сам текст правила. Конечно же, это делается в благих целях. Но у всех свое "усмотрение". И цели иногда отличаются. В итоге правило оказыватся разным для каждого. Начинается хаос — то, что правила призваны избежать.

Если вам кажется, что соблюдение правила заставляет вас сделать что-то лишнее, все-таки сделайте. Иначе завтра ваш коллега не последует какому-нибудь еще правилу. Он будет иметь моральное право на это, потому что сегодня вы сделали так же. Коллега сделает что-то в обход правил, по своему усмотрению. А его "усмотрение" может не понравиться вам.

Поэтому не пренебрегайте правилами.

В комментариях в коде пиши, почему сейчас сделано именно так.

В коммит-месседжах пиши, почему что-то поменяли.

В тикетах пиши, как расследовали баг, как добавляли фичу.

В вики пиши все остальное, в том числе, что не связано с конкретными изменениями в коде. Проставляй ссылки на вики отовсюду, где есть что-от близкое по теме.

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

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

Потом, когда буду искать концы, тебе скажут спасибо. Или ты сам себе скажешь.

• Заголовок коммит-месседжа должен содержать самую суть. Он должен быть максимально конкретным, но при этом быть понятным каждому, кто активно работает с репозиторием.
• Тело коммит-месседжа должно отвечать на вопрос "зачем". И, возможно, освещать подробности того, что именно сделано. Только в самых очевидных случаев тело коммит месседжа можно опускать.
• Дифф должен быть минимальным. Нелья делать изменения "заодно". Разные задачи — разные изменения. Правило пионера скаута — это хорошо, но оставляйте после себя чистую поляну отдельным коммитом с объяснениями. Рефакторинг и изменения поведения, в том числе и фиксы, —в разных коммитах. Ревьюер должен понимать, на что ему обратить внимание: корректность, проектирование, формат кода.

Все перечисленное выше также поможет при копании в истории системы контроля версий при расследовании багов.

На большинствро случаев жизни есть специальные типы контейнеров и отображений (mapping). Пример из Питона. Небольшое количество элементов — Collection. То же, но где порядок имеет смысл и нужно уметь обращаться по индексу — Sequence. Что-то длинное, по чему разрешается только один раз проитерироваться — Iterable. Нужно по одному значению получать другое — Mapping. Это относится как к возвращаемым типам, так и к типам параметров. Даже если текущая реализация функции возвращает конкретно список, надо указывать как к этому списку нужно относиться: важен ли в нем порядок, можно ли по нему много раз пройтись. Даже если текущая реализация функции проходит по контейнеру в цикле один раз, надо в аннотации указывать то, чем является параметр по сути и какие гарантии вы как автор можете дать на будущее.

Есть также изменяемые (mutable) типы контейнеров и отображений. Если вам на самом деле хочется менять параметр или, тем более, указывать, что можно менять возвращаемое значение, подумайте как следует, стоит ли оно того. Изменения состояния должны очень хорошо контролироваться. В идеале состояние должно быть инкапсулировано в класс, и любые изменения должны производиться через его методы. Но это тема для другой статьи.

В функции параметр — контравариантный тип, а возвращаемое значение — ковариантный. Более частный тип параметра означает более общий тип функции. Если функция имеет более общий тип параметра, она подходит туда, где требуется функция с более частным типом параметра. Это и есть контравариантность. С возвращаемым типом все прямее: более частный возвращаемый тип — более частный тип функции.

Нет никаких правил вроде "возвращайте наиболее частный тип, а принимайте наиболее общий". Откуда это пошло? Это всего лишь вежливость разработчика библиотеки. Это способ сделать функцию наиболее универсальной для клиентского кода, дать максимум гарантий.

Мало гарантий — неудобно клиентскому коду. Много гарантий — неудобно библиотеке. Гарантии надо выбирать раузмно.

Представления о прекрасном должны быть общие на команду или проект. Они должны обладать более высоким приоритетом, чем представления о прекрасном каждого разработчика в отдельности.

Правила нужны, чтобы не тратить время на споры о вкусах.

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

Но чем больше правил и чем они сложнее, тем труднее их соблюдать и проверять.

Когда правил много, — это тоталитризм. Когда правил мало — это анархия.

Тоталитаризм — это дисциплина и стабильность. Никаких лишних разговоров и споров. Тоталитаризм требует грамотоного управления. Иногда высокая зарегулированность может быть причиной демотивации. Новичков нужно вводить аккуратно. Есть риск, что они могут не прижиться.

Анархия — свобода, самовыражение, быстрые изменения. Если задача подразумевает proof of concept, первую версию чего-либо или быстрый фикс, то разумная доля анархии может оказаться выгодной.

Выбирайте нужную точку на континууме между тоталитаризмом и анархией в зависимости от команды, проекта и задачи.

Производители дисков указывают объем в десятичных приставках.

Объемы информации измеряются в байтах с двоичными приставками.

Процессоры работают с байтами. В общем случае байт — это не всегда 8 бит. Поэтому придумали слово "октет". Отсюда пошло application/octet-stream.