@sovetov

Unicode не кодировка

2021-08-15T15:46:31.597Z

Кодировки — это UTF-8, UTF-16, UCS-2. Они определяют, как записать конкретные код-поинты (номера символов) в байты. А Unicode — это как раз набор символов и частей символов, рекомендации по их сочетаемости и отображению, по тому как работать с разными системами письма.

JSON — это не вложенные дикты, листы и скаляры

2021-08-15T15:36:24.128Z

JSON — это последовательность байтов. Байты представляют из себя строку текста в в UTF-8. В которую закодированы вложенные дикты, листы, инты, флоаты, строки и наны. Пример:

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.

Хороший код

2021-08-14T18:11:51.867Z

Не существует хорошего кода. Либо он бестолковый и никому не нужный, но нравится автору, либо оброс кучей обременений совместимости и техническим долгом. Возможно, где-то его пишут, но уж точно не в опенсорс.

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

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

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

Правилами нельзя пренебрегать

2021-08-12T11:19:06.367Z

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

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

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

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

Записывай все, что знаешь

2021-07-29T12:44:03.607Z

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

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

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

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

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

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

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

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

Как будут ревьюить твой код

2021-07-29T11:52:11.201Z

Ревьюер (обычно) не несет ответственности за код. Его задача — помочь. Если помогать долго и трудно, никто это делать не будет. Посмотрят поверхностно на код-стайл и махнут рукой. Поэтому надо сделать так, чтобы ревьюер мог легко и комфортно вникнуть в суть изменения. Поэтому:

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

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

Какие типы возвращать и принимать

2021-07-26T11:09:56.641Z

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

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

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

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

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

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

Правила должны быть простыми

2021-07-22T15:44:00.539Z

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

Правила: зачем и какие нужны

2021-07-22T14:47:56.913Z

Правила нужны не только для того, чтобы код был читаемым или качественным. Читаемость, в конце концов, — субъективная характеристика. У всех свои представления о прекрасном.

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

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

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

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

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

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

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

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

Килобиты и килобайты

2021-07-21T18:13:26.957Z

Сетевые скорости и битрейты аудио и видео измеряются в битах в секунду с десятичными приставками. 100 Мбит/с — это 100000000 бит в секунду. Низкоуровневые сетевые протоколы никак не привязаны к байтам, октетам и, тем более, степеням двойки. Оттуда все и пошло.

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

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

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