javascript правила оформления кода
7 рекомендаций по оформлению кода на JavaScript
Автор материала говорит, что она прямо-таки одержима написанием чистого кода. Она считает, что код надо писать так, чтобы, во-первых, с ним, в будущем, удобно было бы работать другим программистам, включая его автора, а во-вторых — с учётом возможности расширения этого кода. То есть, нужно стремиться к тому, чтобы в приложение сравнительно просто было бы добавлять новые возможности, и чтобы его кодовую базу было бы удобно сопровождать. Если бы программы писали, учитывая лишь нужды компьютеров, то, вероятно, программисты могли бы выражать свои мысли лишь с помощью нулей и единиц, больше ни о чём не заботясь. В этой статье приводится ряд рекомендаций по написанию качественного кода, проиллюстрированных примерами на JavaScript.
1. Используйте понятные имена переменных и функций
Код гораздо легче читать, когда при его написании используют понятные, описательные имена функций и переменных. Вот не очень понятный код:
Его читабельность значительно улучшится, если использовать в нём понятные имена переменных и функций, отражающие их смысл.
Не стремитесь к минимализму при написании текстов программ. Используйте полные имена переменных, которые тот, кто будет работать с вашим кодом в будущем, легко сможет понять.
2. Пишите короткие функции, решающие одну задачу
Её можно разбить на две функции, тогда роль каждого фрагмента кода станет более понятной. Кроме того, если мы создаём большую программу, наличие функции sumArray может оказаться очень кстати. Вот код двух новых функций. Одна вычисляет сумму элементов массива, вторая возвращает их среднее значение.
Признаком того, что функцию можно разбить на две, является возможность использования слова «and» в её имени.
3. Документируйте код
Пишите хорошую документацию к своему коду — тогда тот, кто столкнётся с ним в будущем, поймёт, что и почему в этом коде делается. Вот пример неудачной функции. Здесь используются некие «магические числа», их смысл нигде не пояснён.
Сюда можно добавить комментарии для того, чтобы этот код стал бы более понятным для того, кто не знает формулы для вычисления площади круга.
Комментарии к коду должны отвечать на вопрос «почему».
Обратите внимание на то, что для целей документирования кода имеет смысл воспользоваться специальными инструментами и соответствующими им правилами комментирования кода. В применении к Python мне нравится Google Style Docstrings, в применении к JavaScript — JSDoc.
4. Подумайте об использований правил Сэнди Метц
Сэнди Метц отлично программирует на Ruby, делает интересные доклады и пишет книги. Она сформулировала четыре правила написания чистого кода в объектно-ориентированных языках. Вот они.
Рекомендую посмотреть её выступление, касающееся этих правил.
Я следую этим правилам уже примерно два года, и они так основательно закрепились в моём сознании, что я выполняю их, буквально, «на автомате». Мне они нравятся, и я полагаю, что благодаря их использованию повышается удобство сопровождения кода.
Обратите внимание на то, что данные правила — это лишь рекомендации, но их использование позволит сделать ваш код значительно лучше.
5. Применяйте выбранные правила последовательно
Последовательное применение правил написания кода очень важно независимо от того, пишете ли вы код некоего проекта самостоятельно или работаете в команде. В частности, выражается это в том, что тот, кто читает код, являющийся результатом командной разработки, должен воспринимать его как единое целое. При таком подходе авторство отдельных строк кода можно установить, лишь обратившись к Git. Если вы, в JavaScript, используете точку с запятой — ставьте её везде, где это нужно. То же самое касается и кавычек — выберите двойные или одинарные кавычки и, если на то нет веских причин, всегда используйте то, что выбрали.
Рекомендую применять руководство по стилю кода и линтер, который позволяет приводить код к выбранному стандарту. Например, мне, для JavaScript, нравятся правила Standard JS, для Python — правила PEP8.
На самом деле, главное здесь — найти правила оформления кода и их придерживаться.
6. Помните о принципе DRY
Одна из первых идей, которую стараются донести до того, кто хочет стать программистом, звучит так: «не повторяйся» (Don’t Repeat Yourself, DRY). Если вы замечаете в своих проектах повторяющиеся фрагменты — используйте такие программные конструкции, которые позволят сократить повторы одного и того же кода. Я часто советую моим ученикам поиграть в игру SET для того, чтобы улучшить их навыки по распознаванию шаблонов.
Однако если вы приметесь фанатично применять принцип DRY или решите абстрагировать неудачно выбранные шаблоны, читаемость кода может серьёзно ухудшиться, и, позже, вам может понадобиться чаще прибегать к созданию копий одних и тех же конструкций. У Сэнди Метц, кстати, есть отличная статья, посвящённая тому, что дублирование кода — это меньшее зло, нежели неудачная абстракция.
В результате, не стоит повторяться, но и не стоит, в борьбе за соблюдение принципа DRY, видоизменять код до такой степени, что он может стать трудным для понимания.
7. Используйте идеи инкапсуляции и модульности
Группируйте связанные переменные и функции для того, чтобы сделать ваш код понятнее и улучшить его с точки зрения его повторного использования. Вот пример не самого удачно организованного кода, в котором сведения о человеке оформлены в виде отдельных переменных.
Если в подобной программе нужно обрабатывать данные многих людей, тогда в ней лучше будет использовать нечто вроде следующей конструкции.
А если в программе надо работать лишь с данными об одном человеке, то их можно оформить так, как показано ниже.
Похожим образом следует подходить к разбиению длинных программ на модули, на отдельные файлы. Это облегчит использование кода, выделенного в отдельные файлы, в разных проектах. В больших файлах с программным кодом часто тяжело ориентироваться, а небольшие понятные модули легко использовать и в том проекте, для которого они созданы, и, при необходимости, в других проектах. Поэтому стремитесь к написанию понятного модульного кода, объединяя логически связанные элементы.
Итоги
В этом материале мы поделились с вами некоторыми рекомендациями по написанию чистого и понятного кода. Однако, это — лишь рекомендации. Это — советы, способствующие написанию качественных текстов программ. Если систематически применять правила, подобные изложенным здесь, то, в сравнении с кодом, при написании которого нечто подобное не применяется, код, написанный с использованием правил, будет получаться более понятным, его легче будет расширять, сопровождать и использовать повторно.
Правила оформления JavaScript-кода
1. Объекты
1.1 Создание объекта
1.2 Зарезервированные слова
Не используйте зарезервированные слова в качестве ключей объектов. Они не будут работать в IE8.
1.3 Ключевые слова
Не используйте ключевые слова (в том числе измененные). Вместо них используйте синонимы.
1.4 Создание обьекта на 3 и более элементов.
При создании обьектов, равно как и массивов, содержащих большое количество свойств(элементов), и тем самым образующих строки, длиной более 20 символов, необходимо выполнять ряд условий:
2. Переменные
Для именования переменных используйте существительные на английском языке(не транслит!). Имя переменной должно быть осмысленным.
3. Функции
3.1 Именование функции
Имя функции должно быть глаголом на английском языке или начинаться с него. Для имён, состоящих из нескольких слов, используйте camelCase.
3.2 Передача функции в функцию
При передаче функции, как аргумент в другую функцию, оформляйте код как в примере ниже.
4. Отступы
4.1 Горизонтальные отступы
4.2 Вертикальные отступы
Между логическими блоками(циклами, функциями и т.д.) следует оставлять пустую строку. Это делает код более читабельным. Избегайте блоков кода более 9 строк подряд.
5. Пробелы
6. Скобки
Открывающая фигурная скобка располагается на той же строке. Перед скобкой пробел. Закрывающая скобка располагается на новой строке.
7. Кавычки
Всегда в коде скрипта используйте одинарные кавычки, если не требуется иного. Двойные кавычки допустимы, если в этой же строке необходимо использовать апостроф (‘) или одинарные кавычки для других целей.
8. Точка с запятой
В конце выражения обязательна точка с запятой.
9. Комментарии
Для пояснения кода используются комментарии. Комментарии не исполняются интерпретатором JavaScript.
Руководство по JavaScript, часть 1: первая программа, особенности языка, стандарты
Недавно мы провели опрос, посвящённый целесообразности перевода этого руководства по JavaScript. Как оказалось, около 90% проголосовавших отнеслись к данной идее положительно. Поэтому сегодня публикуем первую часть перевода.
Это руководство, по замыслу автора, рассчитано на тех, кто уже немного знаком JavaScript и хочет привести свои знания в порядок а также узнать о языке что-то новое. Мы решили немного расширить аудиторию этого материала, включить в неё тех, кто совершенно ничего не знает о JS, и начать его с написания нескольких вариантов «Hello, world!».
Hello, world!
Программа, которую по традиции называют «Hello, world!», очень проста. Она выводит куда-либо фразу «Hello, world!», или другую подобную, средствами некоего языка.
JavaScript — это язык, программы на котором можно выполнять в разных средах. В нашем случае речь идёт о браузерах и о серверной платформе Node.js. Если до сих пор вы не написали ни строчки кода на JS и читаете этот текст в браузере, на настольном компьютере, это значит, что вы буквально в считанных секундах от своей первой JavaScript-программы.
Этот текст можно ввести с клавиатуры, можно скопировать и вставить его в консоль. Результат будет одним и тем же, но, если вы учитесь программировать, рекомендуется вводить тексты программ самостоятельно, а не копировать их.
Первая программа в консоли браузера — вывод сообщения в консоль
Ещё один вариант браузерного «Hello, world!» заключается в выводе окна с сообщением. Делается это так:
Вот результат выполнения этой программы.
Вывод сообщения в окне
Обратите внимание на то, что панель инструментов разработчика расположена теперь в нижней части экрана. Менять её расположение можно, воспользовавшись меню с тремя точками в её заголовке и выбирая соответствующую пиктограмму. Там же можно найти и кнопку для закрытия этой панели.
Инструменты разработчика, и, в том числе, консоль, имеются и в других браузерах. Консоль хороша тем, что она, когда вы пользуетесь браузером, всегда под рукой.
7 рекомендаций по оформлению кода на JavaScript
Автор материала, перевод которого мы публикуем сегодня, говорит, что она прямо-таки одержима написанием чистого кода. Она считает, что код надо писать так, чтобы, во-первых, с ним, в будущем, удобно было бы работать другим программистам, включая его автора, а во-вторых — с учётом возможности расширения этого кода. То есть, нужно стремиться к тому, чтобы в приложение сравнительно просто было бы добавлять новые возможности, и чтобы его кодовую базу было бы удобно сопровождать. Если бы программы писали, учитывая лишь нужды компьютеров, то, вероятно, программисты могли бы выражать свои мысли лишь с помощью нулей и единиц, больше ни о чём не заботясь. В этой статье приводится ряд рекомендаций по написанию качественного кода, проиллюстрированных примерами на JavaScript.
1. Используйте понятные имена переменных и функций
Код гораздо легче читать, когда при его написании используют понятные, описательные имена функций и переменных. Вот не очень понятный код:
Его читабельность значительно улучшится, если использовать в нём понятные имена переменных и функций, отражающие их смысл.
Не стремитесь к минимализму при написании текстов программ. Используйте полные имена переменных, которые тот, кто будет работать с вашим кодом в будущем, легко сможет понять.
2. Пишите короткие функции, решающие одну задачу
Её можно разбить на две функции, тогда роль каждого фрагмента кода станет более понятной. Кроме того, если мы создаём большую программу, наличие функции sumArray может оказаться очень кстати. Вот код двух новых функций. Одна вычисляет сумму элементов массива, вторая возвращает их среднее значение.
Признаком того, что функцию можно разбить на две, является возможность использования слова «and» в её имени.
3. Документируйте код
Пишите хорошую документацию к своему коду — тогда тот, кто столкнётся с ним в будущем, поймёт, что и почему в этом коде делается. Вот пример неудачной функции. Здесь используются некие «магические числа», их смысл нигде не пояснён.
Сюда можно добавить комментарии для того, чтобы этот код стал бы более понятным для того, кто не знает формулы для вычисления площади круга.
Комментарии к коду должны отвечать на вопрос «почему».
Обратите внимание на то, что для целей документирования кода имеет смысл воспользоваться специальными инструментами и соответствующими им правилами комментирования кода. В применении к Python мне нравится Google Style Docstrings, в применении к JavaScript — JSDoc.
4. Подумайте об использований правил Сэнди Метц
Сэнди Метц отлично программирует на Ruby, делает интересные доклады и пишет книги. Она сформулировала четыре правила написания чистого кода в объектно-ориентированных языках. Вот они.
Я следую этим правилам уже примерно два года, и они так основательно закрепились в моём сознании, что я выполняю их, буквально, «на автомате». Мне они нравятся, и я полагаю, что благодаря их использованию повышается удобство сопровождения кода.
Обратите внимание на то, что данные правила — это лишь рекомендации, но их использование позволит сделать ваш код значительно лучше.
5. Применяйте выбранные правила последовательно
Последовательное применение правил написания кода очень важно независимо от того, пишете ли вы код некоего проекта самостоятельно или работаете в команде. В частности, выражается это в том, что тот, кто читает код, являющийся результатом командной разработки, должен воспринимать его как единое целое. При таком подходе авторство отдельных строк кода можно установить, лишь обратившись к Git. Если вы, в JavaScript, используете точку с запятой — ставьте её везде, где это нужно. То же самое касается и кавычек — выберите двойные или одинарные кавычки и, если на то нет веских причин, всегда используйте то, что выбрали.
Рекомендую применять руководство по стилю кода и линтер, который позволяет приводить код к выбранному стандарту. Например, мне, для JavaScript, нравятся правила Standard JS, для Python — правила PEP8.
На самом деле, главное здесь — найти правила оформления кода и их придерживаться.
6. Помните о принципе DRY
Одна из первых идей, которую стараются донести до того, кто хочет стать программистом, звучит так: «не повторяйся» (Don’t Repeat Yourself, DRY). Если вы замечаете в своих проектах повторяющиеся фрагменты — используйте такие программные конструкции, которые позволят сократить повторы одного и того же кода. Я часто советую моим ученикам поиграть в игру SET для того, чтобы улучшить их навыки по распознаванию шаблонов.
Однако если вы приметесь фанатично применять принцип DRY или решите абстрагировать неудачно выбранные шаблоны, читаемость кода может серьёзно ухудшиться, и, позже, вам может понадобиться чаще прибегать к созданию копий одних и тех же конструкций. У Сэнди Метц, кстати, есть отличная статья, посвящённая тому, что дублирование кода — это меньшее зло, нежели неудачная абстракция.
В результате, не стоит повторяться, но и не стоит, в борьбе за соблюдение принципа DRY, видоизменять код до такой степени, что он может стать трудным для понимания.
7. Используйте идеи инкапсуляции и модульности
Группируйте связанные переменные и функции для того, чтобы сделать ваш код понятнее и улучшить его с точки зрения его повторного использования. Вот пример не самого удачно организованного кода, в котором сведения о человеке оформлены в виде отдельных переменных.
Если в подобной программе нужно обрабатывать данные многих людей, тогда в ней лучше будет использовать нечто вроде следующей конструкции.
А если в программе надо работать лишь с данными об одном человеке, то их можно оформить так, как показано ниже.
Похожим образом следует подходить к разбиению длинных программ на модули, на отдельные файлы. Это облегчит использование кода, выделенного в отдельные файлы, в разных проектах. В больших файлах с программным кодом часто тяжело ориентироваться, а небольшие понятные модули легко использовать и в том проекте, для которого они созданы, и, при необходимости, в других проектах. Поэтому стремитесь к написанию понятного модульного кода, объединяя логически связанные элементы.
Итоги
В этом материале мы поделились с вами некоторыми рекомендациями по написанию чистого и понятного кода. Однако, это — лишь рекомендации. Это — советы, способствующие написанию качественных текстов программ. Если систематически применять правила, подобные изложенным здесь, то, в сравнении с кодом, при написании которого нечто подобное не применяется, код, написанный с использованием правил, будет получаться более понятным, его легче будет расширять, сопровождать и использовать повторно.
Уважаемые читатели! Каких правил оформления кода придерживаетесь вы?
Рекомендации по написанию чистого кода на JavaScript
Если вы заботитесь о самом коде, и о том, как он написан, а не заняты лишь тем, чтобы создавать работающие программы, это означает что вы стремитесь к тому, чтобы ваш код был чистым. Профессиональный разработчик пишет код не только в расчёте на компьютеры, но и в расчёте на себя самого, встретившего этот код в будущем, и в расчёте на других программистов. Код, который вы пишете, не исчезает навсегда в недрах компьютера. Он живёт, изменяется, и, если написан плохо, вполне может сильно расстроить того, кому придётся редактировать его после того, как вы его написали. Вполне возможно, что этим «кем-то» будете именно вы.
Исходя из этих идей, чистый код можно определить как код, написанный так, что он сам себя объясняет. Этот код без труда смогут понять люди, его легко будет модифицировать или расширять.
Код и WTF-вопросы
Сущность WTF-вопросов, вроде «WTF is that?», сводится к крайнему удивлению и возмущению. По-русски эти чувства можно выразить вопросом «Какого чёрта?». «Чёрт», в зависимости от ситуации, вполне может уступить место чему-нибудь совершенно непечатному. Сколько раз вам доводилось дописывать чей-то код и при этом задаваться подобными вопросами?
Задавая себе WTF-вопросы о чужом коде, программисты спрашивают себя о том, что это такое (WTF is that?), что пытался сделать автор кода (WTF did you do here?), зачем в коде присутствует та или иная конструкция (WTF is this for?)
Вот картинка, в соответствии с которой единственным достоверным показателем качества кода является количество WTF-вопросов в минуту.
Слева — хороший код. Справа — плохой
А если серьёзно, то для того чтобы помочь вам настроиться на размышления о чистом коде, процитируем Роберта Мартина, известного как дядюшка Боб: «Даже плохой программный код может работать. Однако если код не является «чистым», это всегда будет мешать развитию проекта».
Теперь рассмотрим некоторые практические рекомендации по написанию чистого кода. Мы будем использовать здесь JavaScript, но эти рекомендации можно применить и к разработке на других языках.
1. Строгие проверки на равенство
2. Переменные
Называйте переменные так, чтобы их имена раскрывали бы их сущность, их роль в программе. При таком подходе их удобно будет искать в коде, а тот, кто увидит этот код, легче сможет понять смысл выполняемых им действий.
Плохо:
Не надо добавлять в имена переменных дополнительные слова, в которых нет необходимости.
Не стоит принуждать того, кто читает код, к тому, чтобы ему приходилось бы помнить о том, в каком окружении объявлена переменная.
Не нужно снабжать имена переменных избыточными сведениями о контексте, в котором они используются.
3. Функции
Используйте для функций длинные описательные имена. Учитывая то, что функция представляет собой описание выполнения некоего действия, её имя должно представлять собой глагол или фразу, полностью описывающую суть функции. Имена аргументов нужно подбирать так, чтобы они адекватно описывали бы представляемые ими данные. Имена функций должны сообщать читателю кода о том, что именно делают эти функции.
Избегайте использования длинных списков аргументов. В идеале функции следует иметь два или меньшее количество аргументов. Чем меньше у функции аргументов — тем легче будет её тестировать.
Используйте аргументы по умолчанию, отдавая им предпочтение перед условными конструкциями.
Функция должна решать одну задачу. Стремитесь к тому, чтобы одна функция не выполняла бы множество действий.
Используйте Object.assign для установки свойств объектов по умолчанию.
Не используйте флаги в качестве параметров. Их использование означает, что функция выполняет больше действий, чем ей следовало бы выполнять.
Не загрязняйте глобальную область видимости. Если вам нужно расширить существующий объект — используйте ES-классы и механизмы наследования вместо того, чтобы создавать функции в цепочке прототипов стандартных объектов.
4. Условные конструкции
Старайтесь не называть логические переменные так, чтобы в их именах присутствовало бы отрицание. То же самое касается и функций, возвращающих логические значения. Использование таких сущностей в условных конструкциях затрудняет чтение кода.
Избегайте логических конструкций везде, где это возможно. Вместо них используйте полиморфизм и наследование.
5. ES-классы
Классы появились в JavaScript сравнительно недавно. Их можно назвать «синтаксическим сахаром». В основе того, что получается при использовании классов, лежат, как и прежде, прототипы объектов. Но код, в котором применяются классы, выглядит иначе. В целом, если есть такая возможность, ES-классы стоит предпочесть обычным функциям-конструкторам.
6. О том, чего лучше не делать
Тому, кто хочет, чтобы его код был бы чистым, стоит стремиться к тому, чтобы не повторяться. Речь идёт о том, что нужно избегать ситуаций, в которых приходится писать один и тот же код. Кроме того, не нужно оставлять в кодовой базе неиспользуемые функции и фрагменты программ, которые никогда не выполняются.
Дублирующийся код может появляться по разным причинам. Например, в проекте может быть пара слегка отличающихся друг от друга функций. Природа этих отличий или нехватка времени принуждают программиста, например, к созданию двух самостоятельных функций, содержащих практически идентичный код. В подобной ситуации избавление от дублирующегося кода заключается в абстрагировании различий и в работе с ними на более высоком уровне.
Теперь поговорим о неиспользуемом коде. Это — код, который присутствует в кодовой базе, но совершенно ничего не делает. Такое случается, например, когда на определённом этапе разработки решают, что в некоем фрагменте программы больше нет смысла. Для того чтобы избавиться от подобных фрагментов кода, нужно внимательно просмотреть кодовую базу и убрать их. Легче всего избавляться от такого кода в тот момент, когда решено, что он больше не нужен. Позже можно забыть о том, для чего он использовался. Это значительно усложнит борьбу с ним.
Если отложить борьбу с ненужным кодом, то программа будет напоминать то, что показано на следующем рисунке.
Иногда мой код похож на этот балкон. Не знаю — какую задачу он решает, но опасаюсь от него избавиться
Итоги
Здесь мы обсудили лишь малую часть тех действий, которые можно предпринять для улучшения кода. Автор этого материала полагает, что о рассмотренных здесь принципах часто забывают. Программисты пытаются им следовать, но, по разным причинам, не всегда в этом преуспевают. Возможно, в самом начале работы над проектом все помнят о важности чистого кода, в результате программа получается аккуратной. Потом же, по мере приближения дедлайнов, о чистоте кода часто забывают, обращая внимание лишь на то, что отмечено как TODO или REFACTOR. В такие моменты заказчик проекта будет настаивать на том, чтобы проект завершили в срок, а не на том, чтобы его код был бы чистым.
Мы довольно часто публикуем материалы, посвящённые проблеме написания качественного JavaScript-кода. Если вам эта тема интересна — вот несколько ссылок.
Уважаемые читатели! Доводилось ли вам задаваться WTF-вопросами при чтении чужого кода?