О JSdoc замолвите слово…
Погружение новичка в уже разрабатываемый проект редко бывает легким. Мы привыкаем к соглашениям внутри отдела и не обращаем внимание на такие мелочи, как комментарии.
Сейчас я новичок на новой работе. Передо мной море работ по фронтенду на базе React/Redux и т.д. Я девочка, поэтому красоту наводить буду я. Бекенд трогать не буду.
Мне показали как собрать проект, библиотеку статических компонентов React, написанную другим отделом. И тут началось…
Комментариев в коде было найдено примерно в 5% просмотренного, и этот код не был ключевыми для понимания структуры проекта. Было приятно находить описание, как подключать то или иное поле в форму, с примерам, где код полностью соответствовал jsdoc. Во всех остальных случаях я чувствовала себя Шерлоком, где улики приходилось по цепочке искать, начиная с package.json.
Новая семья
Мой опыт взаимодействия с React был ограничен видеоуроками на youtube(раз, два), просмотренных где-то с полгода назад, и парой статей с Хабра.
Первые свидания давно прошли, предложение руки и сердца было сделано — пора начинать суровые семейные будни.
Что нужно для начала: несколько кулинарных книг (спасибо Максиму Пацианскому), договор с клининговой службой(вы пробовали заставить убирать детей?) и много общения в семье.
Клинингом занялся ESlint. Создавать с нуля свои правила с маленьким опытом разработки jsx компонентов было бы глупо. Поэтому взяла готовую конфигурацию от Марты Стюарт Airbnb и добавила в нее немного мазохизма (о, да!) в виде обязательных jsdoc комментариев согласно стандарту. Семейная мудрость заключалась в том, чтобы настроить в WebStorm/Intellij Idea автоматическую подсветку ошибок — отклонения от конфигурации линтера. Обязательные комментарии, пусть насильно, но облегчат жизнь всему коллективу, да и вам через долгое время. Думаю, многие слышали про автоматическую генерацию документации. В Java это вроде бы много где уже стало нормой, а вот про JavaScript такого не замечала (если верить сплетням).
Для генерации документации вам понадобится подключить пакет npm и настроить вашу IDE по инструкции.
У меня бывали случаи отсутствия документации по открытой библиотеке, но с хорошими комментариями — генерация документации по ним очень помогала разобраться в замысловатых конструкциях.
Раньше я работала вместе с человеком, который, как казалось, слишком много внимания уделял комментария и разжевыванию каждой строчки кода. Прошу меня простить за высокомерие — много комментариев не бывает (! только не оставляйте банальные переводы имен методов.
Я новичок, на меня возлагают большие надежды, я покажу какая я умная… Бла-бла-бла. Тупить по два-три часа, потому что не можешь найти Object, в то время как тебе возвращают Map — вот это глупость. Не стесняться задать лишний вопрос, ставить себе лимиты времени на поиск ответов на один вопрос, после чего идти задавать вопросы и просить о помощи — вот умное поведение. Тебя никто не скушает (особенно, если ты хрупкая девочка) — тебе будут рады помочь. Излишняя интровертность много раз становилась причиной попадания впросак. Учиться нужно не только программировать, но и общаться.
Это мои первые выводы об адаптации на новой работе. А что бы вы посоветовали для улучшения погружения новобранцев?
Комментарии (21)
Houston
01.03.2017 22:31+3Не всё так однозначно ©.
JSDoc обычно нужен разве что для библиотек, в конечном проекте оверхед по его поддержке не окупится.
Читаем Боба Мартина и его "Чистый код" – комментарии не нужны.
Конечно, у этого правила есть исключения – хаки, TODO-шки, оптимизации и ссылки на баги в трекере. Но большинство кода должно быть написано так, чтобы комментарии были не нужны.
yulllll
01.03.2017 22:49-1Книжка классная — это одна из обязательных, на мой взгляд, книг на программистской полке. На практике, я пока не встречала полного воплощения идей Мартина. Поэтому предлагаю «насильственное» применение jsdoc (было потрачено много рабочих часов на разбор кода)
Houston
01.03.2017 22:57Конечно же, всё индивидуально, и если вам и вашей команде так удобнее – то никто не вправе вам говорить, что так не правильно.
Хотел бы поделиться таким наблюдением – с ростом опыта в проекте (и в используемой технологии) мозг воспринимает больше информации за раз. И тогда простыни комментариев только мешают.
raveclassic
02.03.2017 00:07Я тоже внедрял jsdoc в команде насильственно. Сейчас все только довольны.
На данный момент в процессе внедрения TS, думаю результат будет таким же.
seokirill
01.03.2017 22:49Не соглашусь. Я сейчас работаю над проектом в команде, помимо нас еще десяток-другой команд из разных компаний. Jsdoc + typescript очень помогает, особенно это ощущается, когда натыкаешься на старый код, где всего этого нет.
MrCheater
01.03.2017 23:02+2Мне кажется, команда вам за вашу деятельность спасибо не скажет. Одно дело документация к библиотеке, а другое к пачке бесполезных одноразовых классов-компонентов на React-е.
JSdoc вам особо не поможет. Код React-компонента должен быть просто и понятный. Props приняли, в Render пачку vdom-element-ов отдали.
Если есть какой-то достойный компонент, который можно переиспользовать — делайте npm-пакет и пишите туда нормальную доку.
В Redux с его огромными Switch-ами внутри одной функции JSdoc вам тоже не поможет. ActionCreator-ы — ну ладно, еще куда ни шло — можно пояснить, что функция делает, но, по-хорошему, должно быть понятно из её названия.
Структура папок и билдежка везде примерно одинаковая — лучше потратьте свое время на чтение кода чужих проектов, например, https://github.com/ModusCreateOrg/budgeting-sample-app-webpack2. И перетащите команду на Webpack 2 (если они еще не переехали)
k12th
02.03.2017 01:30-1jsdoc, конечно, лучше чем ничего, но все-таки от TypeScript больше пользы. Другое дело, что какая-никакая, а кривая обучения и порог входа там все-таки есть, а jsdoc очень трудно написать неправильно (хотя люди и не с таким справляются).
SDSWanderer
02.03.2017 02:44Хорошо быть хрупкой девочкой которая пишет на реакте и наводит красоту. Ок.
i360u
02.03.2017 05:37Правильное именование сущностей и внятная структура кода избавляют от необходимости писать комменты и использовать автодок. Для многих и лично для меня, читать код обильно приправленный комментариями очевидного — мучительно. Особенно если комменты на русском. Все, что необходимо новичку в проекте (если он не новичок в используемом стеке), это нормальный актуальный ридми с основами в корне проекта (ну или типа того).
Lailore
tutorial? Реально?
Как по мне это просто выплескивание эмоций одной хрупкой девочки.
yulllll
у вас есть статья-tutorial по настройке рабочего окружения в проектах, связанных с React?
Lailore
Как бы их полно. Включая видео и т.п. включая те по которым вы учились. А у вас не туториал, а максимум описание. Поверхностное.