
Недавно наш отдел геймдизайна поменял основной инструмент и переехал с Google Документов на Notion — хотели решить проблемы хранения и организации документов. В общем, ни разу не пожалели.
Недавно наш отдел геймдизайна поменял основной инструмент и переехал с Google Документов на Notion — хотели решить проблемы хранения и организации документов. В общем, ни разу не пожалели.
JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.
Для создания проекта выполните следующие команды:
mkdir learn-jsdoc && cd learn-jsdoc
- создание каталога проекта.
npm init -y
- инициализация проекта.
touch index.js
- создание файла index.js
Выполните установку JSDoc одним из следующих способов:
Глобально: sudo npm install -g jsdoc
Сегодня поговорим о том, как писать код, чтобы он не злил окружающих и не раздражал вас спустя годы работы, когда вы снова попытаетесь его прочесть.
Я расскажу о подходах, которые мы используем в Яндекс.Такси для написания читаемого кода на 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, (спойлер — не нашли), а нашли возможность глобально улучшить наш процесс работы с документацией.