Сегодня поговорим о том, как писать код, чтобы он не злил окружающих и не раздражал вас спустя годы работы, когда вы снова попытаетесь его прочесть.
Я расскажу о подходах, которые мы используем в Яндекс.Такси для написания читаемого кода на C++, Python, JavaScript и других языках.
Читать полностью »
В последние год-два я пришёл к осознанию того, что основной преградой к выполнению моей работы является документация. Или, если конкретнее, откровенный дефицит документации, предоставляемой Apple для своих платформ.
Apple предоставляет разработчикам набор инструментов — API, позволяющий нам создавать приложения для iOS, iPadOS, macOS и tvOS. Во многих случаях разобраться в том, как пользоваться этими API, достаточно просто. Как отвёртку можно использовать очень немногими способами, так и во многих случаях есть только один очевидный способ применения API.
Читать полностью »
Люди читают пользовательскую документацию, когда самостоятельно не могут с чем-то разобраться. Они не делают это для развлечения. И эмоции, которые преобладают в этот момент, далеко не всегда позитивные. Как разработчик пользовательской документации может помочь пользователю? Что ему необходимо учитывать при написании документа?
А никак они не развивались. С самых первых языков программирования и по сей день комментарии коду — это всего лишь статичный текст (за некоторыми исключениями, о которых я расскажу).
Ну а что там еще можно улучшить или придумать — спросите вы. Давайте поразмышляем на эту тему — можно ли как-то улучшить наш опыт взаимодействия с таким важным но так часто игнорируемым аспектом программирования как документация в коде, или по-простому комментарии.
Читать полностью »
Многие уже давно или активно используют или смотрят в сторону модели хранения и публикации документации как кода, это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду, например, хранить в репозитории, прогонять тесты, собирать и релизить в CI/CD. Этот подход позволяет поддерживать документацию актуальной к коду, версионировать и отслеживать изменения, используя привычные инструменты разработки.
Однако в то же время во многих компаниях годами существуют также и вики-системы, в которых к документации получают доступ другие команды и сотрудники, например, менеджеры проектов. Что если вам захотелось привести хранение и публикацию к единому виду, то есть наряду с HTML публиковать доки и в Confluence? В этой статье я дам обзор решений задачи публикации документов из репозитория в Confluence.
Читать полностью »
Дисклеймер: данная статья не явит вам какого то откровения и не откроет третий глаз, но позволит разобраться в не очень очевидном вопросе более детально. Мне по крайней мере при ее написании она в этом помогла. Если вы матерый волк в php то можете не читать, опытным человекам думаю не повредит пробежать глазами, освежить так сказать в памяти, остальным будет норм.
Итак...
Статические переменные, в php это особый вид переменных, которые объявляются при помощи ключевого слова static.
static $foo = 3;От обычных переменных они отличаются тем что (далее в статье эти пункты будут рассмотрены более подробно):
Теперь по порядку.
Это значит что в статическую переменную не может быть присвоен результат работы какой-либо функции или метода, или вообще что-либо что еще не известно на этапе компиляции. То есть вот такое объявление не сработает
Несколько месяцев назад я закончил один из этапов своего профессионального пути многорукого Шивы в стартапе по разработке системы управления лабораториями неразрушающего контроля. Я расскажу как мне удалось задокументировать часть разработки связанную с подключением и генерацией документов в достаточном объеме для дальнейшего спокойного использования созданной системы в течении двух лет.
Читать полностью »
MS Word регулярно подкидывает нам «сюрпризы»: «съехавшие» скриншоты, «плывущие» таблицы, пустые страницы при печати. Эта статья о том, как мы искали замену MS Word, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.
В статье подробно расскажем в каком формате заказчик должен предоставить информацию исполнителю, для разработки VR проекта и какие материалы необходимо предоставить, для четкого описания проекта своей идеи. Задача заказчика заключается в донесении информации исполнителю, для дальнейшей работы исполнителя с материалом и обучением персонала компании заказчика.
Для общего понимания разберем 3-варианта передачи информации заказчиком, компании исполнителя, для реализации VR проекта.
Читать полностью »
Привет!
Мы тут решили провести митап по DocOps — это почти как DevOps, только про документацию и всё, что с ней связано. Таких мероприятий обычно не так много, оно и понятно — документация не такая хайповая штука, как React, к примеру. Да и не только React, прямо скажем. Злые языки вообще утверждают, что от документации зрение портится.
Но она реально важна, с ней работают люди, и чем правильнее и логичнее у вас в компании выстроены процессы работы с документацией, тем всем будет проще. Даже тем коллегам, работа которых (на первый взгляд) в документацией не связана.
В общем, в пятницу, 26 июля, мы в 19.00 собираемся в Deworkacy (Москва, Берсеневская набережная, 6, стр 3) и начинаем документировать говорить про документацию. Список докладов — под катом.
Читать полностью »
