15 советов по написанию самодокументируемого кода (на примере JavaScript)


Оглавление (нажмите, чтобы открыть):

Переключение с ActionScript на JavaScript, советы по написанию кода?

Мне очень удобно использовать actionscript3 и flash. У меня также есть опыт работы с Java. Но в последнее время я начал изучать JavaScript и node.js. В конечном итоге я хочу сделать 3D-игру в три раза, но сейчас я просто хочу сделать чат-приложение.

Я хочу привыкнуть к использованию JavaScript. К сожалению, мне очень трудно начать использовать JavaScript. Трудности, с которыми я столкнулся, — это

Никаких предложений для разных методов и свойств не появляется, как в среде IDE Eclipse и Flash Builder. Подобно тому, как вы нажимаете точку после объекта, он показывает все методы и свойства, относящиеся к этому объекту, и становится очень легко увидеть, какие параметры необходимо и нужно передавать и прочее.

Как организовать код? В ActionScript3 я мог бы просто создавать разные классы в разных пакетах. Затем я мог импортировать и использовать эти классы в одном основном файле. Как это работает в JavaScript?

Как выполняется код в HTML-файле? Поэтому, если у меня есть несколько тегов , и я объявляю переменную в одном из них, могут ли теги под ним и над ним обращаться к этой переменной?

3 ответа

Javascript — динамический язык, и невозможно приблизиться к тому, что у вас есть в ActionScript или Java. Просто примите то, что может предложить ваша среда IDE (например, WebStorm). Это действительно для любого интерпретируемого языка.

Как организовать код?

Посмотрите requirejs или собственный узел node.js модуль требуют .

Да, используйте их. Javascript очень основан на функциях, поэтому вам просто нужно принять эту часть. Здесь — отличная отправная точка.

Несколько тегов и я объявляю переменную в одном из них, могут ли теги под ним и над ним обращаться к этой переменной?

Нет, только теги под ним. Попробуйте следующее:

Консольные отпечатки «x undefined».

Никаких предложений по разным методам и свойствам не появляется, как в среде IDE Eclipse и Flash Builder. Подобно тому, как вы нажимаете точку после объекта, он показывает все методы и свойства, относящиеся к этому объекту, и становится очень легко увидеть, какие параметры необходимо и нужно передавать и прочее.

На самом деле это не моя чашка чая, но я уверен, что есть плагины Eclipse, которые могут в некоторой степени сделать это для JavaScript. Из-за характера функций и объектной модели в JavaScript было бы намного сложнее сделать это для всех случаев, чем язык, такой как Java.

Как организовать код? В ActionScript3 я мог бы просто создавать разные классы в разных пакетах. Затем я мог импортировать и использовать эти классы в одном основном файле. Как это работает в JavaScript?

Проверьте RequireJS . Насколько мне известно, это наиболее распространенный метод форматирования «модулей» JavaScript (которые являются идиомой JavaScript).

Функции. Я видел, как люди используют анонимные функции в javascript. Но я вынужден писать внешние функции, так как я привык к этому. Что лучше в рабочем процессе JavaScript? Что вы посоветуете?

Вы можете написать много JavaScript без с , чтобы прибегать к анонимным функциям, но анонимные функции упрощают работу. Я думаю, что это то, чему вы можете научиться вовремя.

Как выполняется код в HTML-файле? Поэтому, если у меня есть несколько тегов, и я объявляю переменную в одном из них, могут ли теги под ним и над ним обращаться к этой переменной?

Теги ниже будут иметь доступ к этой переменной. Код выполняется линейно, а область обзора JavaScript проста, ограничена и часто критична (но эффективна, если вы знаете оговорки).

В среде IDE: используйте что-то, у которого есть хорошая поддержка автозаполнения, например, визуальная студия, aptana или webstorm. Это сделает вашу жизнь намного легче.

Для классов, подобных структурам, рассмотрим шаблон модуля.

Посмотрите на книги Дугласа Крокфорда и, возможно, посмотрите какую-нибудь книгу на шаблонах javascript.

Потому что нет никаких классов, это не значит, что нет никаких хороших решения по организации кода.

15 советов по написанию самодокументируемого JavaScript

15 советов по написанию самодокументируемого JavaScript

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

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


Оригинал статьи: https://www.sitepoint.com/self-documenting-javascript/

Эта статья была автоматически добавлена из сообщества Курсы программирования CyberBionic Systematics

Гайд для начинающих: как написать JavaScript

Современный интернет немыслим без скриптов. Учимся писать на JavaScript.

Если бы для интернета писали Библию, она начиналась бы так:

Сначала была почта. И увидели инженеры, что это хорошо. И создали они WWW с гиперссылками. И увидели инженеры, что это тоже хорошо. И создали они тогда язык JavaScript для оживления страничек.

Примерно так происходило в реальности. JavaScript придумали, чтобы «оживить» HTML. Скрипты JavaScript пишутся непосредственно в текст HTML или хранятся в отдельных файлах, как и стили CSS. Они выполняются сразу после загрузки страницы в браузер.

Даже сам язык в первое время назывался LiveScript. Потом его переименовали в JavaScript, потому что планировали как-то увязать с языком общего назначения Java. Но сейчас у них нет практически ничего общего, а JavaScript — совершенно независимый язык программирования со своей четкой спецификацией ECMAScript.

Формально JavaScript является торговой маркой Oracle, а этот язык — «расширение» ECMAScript, наряду с JScript от Microsoft и ActionScript, но это скорее заморочки владельцев торговых марок. Главное, что свободный ECMAScript никому не принадлежит.

Со временем сфера влияния JavaScript значительно расширилась. Его начали использовать не только для скриптов на странице HTML, но и для серьезных больших веб-приложений и целых программ, которые работают в браузере. Есть инструменты, чтобы специальным образом «упаковать» эти программы и выполнять их отдельно от браузера. Это компиляторы и интерпретаторы, которые более подробно рассматриваются на обучающих курсах «Java-разработчик» и «Веб-разработчик».

Приложения JavaScript выполняются в любой среде, где есть соответствующий интерпретатор.

Нас пока интересуют только браузеры и HTML-странички.

Как сделать JavaScript? Написать элементарный скрипт не сложнее, чем простую HTML-страничку, ведь скрипты JavaScript пишутся обычным текстом, то есть их можно создавать буквально в том же «Блокноте», сохраняя потом в отдельных файлах или вставляя в тело HTML-документа. Самые простые вещи на JavaScript делаются действительно просто.

Как написать JavaScript

Для примера сделаем простой скрипт для выполнения сервером сценариев Windows. Этот скрипт можно написать прямо в «Блокноте» и выполнить без браузера.

WScript. echo (» Привет, Skillbox!«)

Пишем этот текст в «Блокноте», затем сохраняем файл под именем skillbox.js и запускаем в «Проводнике» Windows.

Аналогичный скрипт можно записать прямо в коде страницы HTML между тегами . Там уже можно использовать обычные методы JavaScript, а не метод echo специфического объекта WScript. Рассмотрим некоторые из стандартных методов для ввода и вывода данных в браузере.

alert()

Метод alert() отображает окошко с кнопкой «OK». В окне выводится сообщение, которое указано в скобках. Например, «Привет, Skillbox!». То есть в данном случае браузер делает ровно то же самое, что перед этим делал сервер сценариев Windows.

Мастер Йода рекомендует:  Бесплатные игровые движки на HTML5 и JavaScript

Эти примеры тоже можно писать в «Блокноте», только сохранять в файлах с расширением HTML. Например, skillbox.htm.

В качестве аргумента alert() можно указать не только конкретный текст, но и результат каких-либо вычислений или обработки других данных. Например, alert(x), где x вычисляется отдельно.

confirm()

Метод confirm() выводит такое же окно с сообщением, но уже с двумя кнопками — «ОК» и «Отмена». В зависимости от того, какую кнопку щелкнет пользователь, метод возвращает либо значение true, либо false. Сервер получает это возвращаемое значение от пользователя и выполняет какое-то действие, в зависимости от ответа.

Синтаксис такой же, только здесь логически предполагается выбор, так что пользователю задают вопрос.

prompt()

Метод prompt() выводит диалоговое окно с сообщением и текстовым полем, куда пользователь вводит данные. Здесь тоже предусмотрены две кнопки «ОК» и «Отмена». По нажатию первой кнопки метод возвращает на сервер введенный текст, а по нажатию второй кнопки возвращает логическое значение false.

Синтаксис здесь такой:

prompt ( сообщение, значение_поля_ввода_данных)


Значение поля ввода необязательно. Туда можно вписать текст, который изначально введен в поле для удобства пользователя.

Возможности современного JavaScript выходят далеко за рамки примитивного ввода-вывода данных через формы. Эти методы мы привели только в качестве самых простых примеров. Кроме этого, JavaScript позволяет реагировать на действия пользователя. Например, на движения мышкой или нажатие определенных клавиш. JavaScript часто используется для обеспечения асинхронной работы ( Технология AJAX), когда информация на странице обновляется без ее перезагрузки. В этом режиме данные отправляются на сервер и загружаются оттуда в интерактивном режиме. Кроме того, JavaScript способен манипулировать с HTML-элементами на странице (создавать и прятать теги и т.д.) и делать многое другое.

Полезные инструменты

Консоль разработчика

Во всех популярных браузерах есть специальная консоль разработчика. Она показывает код скриптов на странице, а также выводит другую полезную информацию. В Chrome, Firefox и IE консоль разработчика открывается по нажатию горячей клавиши F12, в Safari — Ctrl+Shift+I или Ctrl+Alt+C. На скриншоте скрипты отображаются справа вверху, вместе с другими элементами веб-страницы.

Редакторы кода

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

Для начала можно рекомендовать один из легких редакторов:

В будущем есть смысл присмотреться к IDE:

Заключение

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

Курс идеально подойдет дизайнерам-разработчикам и начинающим программистам, кто уже знаком и умеет разрабатывать страницу на HTML и CSS, но не намерен останавливаться в изучении программирования. Преподаватели практически «на пальцах» объяснят базовые основы синтаксиса JavaScript, научат создавать визуальные интерактивные элементы и помогут разработать первый веб-проект на JavaScript.

Самодокументирование кода в Visual Studio на примере C#

Самодокументирование – механизм описания различных элементов программы (типов, переменных, методов и т.д.) в самом исходном коде [1].

Описание составляется в виде комментария определённой структуры.

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

Visual Studio имеет в своём составе встроенную систему самодокументирования. Рассмотрим её на примере языка программирования C#.

В C# комментарии предназначенные для самодокументирования (комментарии документации) имеют специальное обозначение при помощи символов «///» и форматируются при помощи специальных XML тэгов.

Ниже перечислены XML тэги, рекомендованные Microsoft [2].

Назначение
c Текст, который нужно было бы представить как код.
Позволяет пометить несколько строк как код
example Описание примера кода
Служит для указания возможных исключений.
include Позволяет указать ссылку на файл, в котором содержаться комментарии, используя XPath
Простой список
para Абзац
Описание параметра метода (для каждого параметра отдельное описание)
paramref Позволяет указать, что слово в комментариях кода, например в блоке или , ссылается на параметр
Документирует доступ к члену класса
remarks Описание члена класса
Описание значения, которое возвращает метод
see Ссылка на член класса, который может вызываться из текущей среды компиляции.
Текст в разделе «Смотри также»
summary Общее описание
Объявление универсального типа или метода для описания параметра типа
typeparamref Позволяет указать, что слово в комментариях кода, например в блоке или , ссылается на объявление универсального типа или метода для описания параметра типа
Описание свойства

Тэги typeparam и typeparamref предназначены специально для документирования, так называемых, обобщений.

Синтаксис в тэгах exception, include, param, paramref, permission, see, seealso и typeparam проверяется компилятором.

Комментарии документации лучше всего добавлять перед описываемым элементом программы. В этом случае Visual Studio после ввода символов «///» и нажатия клавиши «Enter», как правило, самостоятельно создаёт необходимую XML структуру комментария.Программисту остаётся только заполнить содержимое XML тэгов.

Ниже приведён пример метода, для которого составлен комментарий документации.

Как сделать документацию к коду?

Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается

Стандартные решения:
1. самодокументируемый код, составленный так, что читающий может понять что для чего и в какой последовательности работает.
2. описание интерфейсов (назначение метода, тип/суть параметров и т.п.) в форме комментов в коде.
3. автоматическая документация (генерится из комментариев) — эффективно, только если сам код закрыт.
4. модульные тесты, фиксирующие требования к коду и демонстрирующие его использование.
5. описание высокоуровневого дизайна (High Level Design, HLD), описывающий какие элементы существуют, их взаимосвязь друг с другом и основные сценарии взаимодействия.

Работающая документация — это компромисс из этих практик, релевантный конкретной ситуации.

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


Думаю, вышеописанные пукнты не вяжутся с JS, хоть и прекрасно работают в других средах (php, java etc).

На JS вообще очень сложно писать «правильно» и «хорошо»))

Правила написания JavaScript кода

Правила написания JavaScript кода

Данный обзор предназначен только для личного использования. Это не сборник абсолютных/идеальных правил, если существующий код уже написан в определённом стиле, то именно ему стоит отдать предпочтение.

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

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

Предполагается использование camelCase стиля именования методов и mixed_underscore для атрибутов и сервисных функций. Подумайте как лучше выразить назначение функции или переменной, скажем массивы лучше именовать во множественном числе, а перед булевыми перемененными использовать is .

Отступы и пробелы

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

Для определения строк используются одинарные кавычки.

Из-за того, что используется явное указание точек-с-запятой всегда начинайте фигурную скобку на той строке, где идёт открывающее выражение. Например:

В целом рекомендуется комментировать сложные моменты и игнорировать очевидный код. Не стоит добавлять бессмысленные, личные или расплывчатые комментарии.

Если оказывается что необходимо постоянно что-то комментировать, подумайте над тем не стоит ли разбить код на именованные функции, описывающие его работу.

При работе с откомментированным кодом не забывайте проверять сохраняется ли актуальность данного комментария и исправлять/удалять его.

Для длинных строк нужно использовать /* . */ .

Длинные одно-строчные комментарии должны быть отдельной строчкой, предпочтительно над комментируемым кодом. Так же перед ними стоит оставлять пустую строку.

Комментарии внутри строки можно использовать только для описания специфических аргументов в списке формальных параметров:

Мастер Йода рекомендует:  Как преодолеть страх перед программированием и кодить уверенно

Массивы и инициализация объектов

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

Отступы многострочных инициализаторов аналогичны таковым у блоков.

Обратите внимание на то, что перед двоеточием пробела нет.

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

Хотя она и назначена осмысленному атрибуту, функция была задана анонимной.

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

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

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

Вызов функции должен содержать пробелы между параметрами, но не должен содержать пробелов около открывающей и закрывающей скобок:

Простые вызовы должны быть в одну строку:


Если функция вызывается со множеством параметров или длинными аргументами, её вызов должен разделяться на название и список аргументов, по одному на строку:

К слову, если аргументы содержат объекты с длинными атрибутами, их стоит тоже записать в несколько строк:

Существует несколько способов создания объектов. В целом рекомендуется использовать паттерн «конструктор»:

Вложенные конструкторы допустимы, но перед этим стоит подумать «а стоит ли».

Часто требуется сохранить ссылку на конструируемый объект для использования во внутренних функциях. Для этого стоит задать переменную self :

Стоит отметить что эта строка всегда идёт в конструкторе первой.

Использование именованных параметров

Использование именованных параметров уменьшает повторения(?) и делает код читабельнее. Их использование особенно полезно если из названия функции не ясно что в неё передавать.

Чтобы в таком коде понять что делает вызов функции, придётся возвращаться к её определению.

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

Что нужно для начала работы функции должно быть очевидно в самом её начале. При её определении либо заносите в var все используемые перемененные, либо комментируйте что из параметров будет использоваться и для чего.

Вложенные функции неплохо подходят для разбиения функционала и могут использоваться свободно. Если функция используется только другой функцией её стоит определить внутри последней.

Как исключение иногда стоит определять дочернюю функцию вне основной с целью избегания перекрёстных ссылок (см. раздел о замыканиях).

Общее поведение может быть сгруппировано в отдельные модули:

В целом рекомендуется создавать по файлу на каждый конструктор или логический блок. Названия должны быть строчными и описывать назначение кода.

Код в представлении

Допустимо использование встроенного JavaScript-кода, но только если инициализаторы связаны с содержимым страницы. В целом код должен быть отделён от представления.

Допустимо встраивать в представление установку констант.

Использование JavaScript в атрибутах HTML противопоказано:

Применяйте ненавязчивый javascript с целью разделить функциональность (слой обработки) от представлений и кода страничек.

Всегда используйте var . Никогда не применяйте неявного приравнивания. Скажем, если хотите создать объект внутри window, так и пишите:

Константы должны определяться аналогично обычным переменным, но при этом следовать своему стилю именования. Ключевое слово ‘const’ плохо поддерживается и его следует избегать.

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

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

После блоков for / while / switch / if / else точки-с-запятой не используются в целях повышения удобочитаемости кода.

Тернарный оператор полезен при назначении переменных. Однако вложенные тернарные операторы недопустимы из-за их низкой читаемости.

Проверка на равенство

В большинстве случаев необходимо использование строгой проверки на (не)равенство ( === and !== ). В частности желательно приведение перемененных перед сравнением.

Проверка типов по возможности должна делаться с помощью именованных методов: arr.isArray , str.isString , func.isFunction , и obj.isObject .


Определение внутри блоков

Как общую практику избегайте объявлений внутри вложенных блоков. Особенно старайтесь избегать определения внутри блоков функций, т.к. это нестандартно для ECMAScript. ECMAScript допускает только определения функций в корневом блоке скрипта или функции(?).

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

Документирование проектов Javascript

Дата публикации: 2020-04-23

От автора: для чего нужно документировать проекты на Javascript? Мы все (надеюсь) знаем, насколько важна хорошая документация и справочные материалы для успешного программного проекта. Без хорошей документации конкретная библиотека может быть недоступна для использования. Без описания того, как разные компоненты и методы работают изолированно, не говоря уже о примерах того, как разные части проекта соотносятся друг с другом, нам остается только интерпретировать первоначальное намерение автора, просто изучая исходный код, или, если повезет, читать StackOverflow и гуглить посты о подобных ошибках. Если это внутренний или небольшой проект, вы, вероятно, можете особо не переживать по этому поводу. Берете на вооружение подход черной магии вуду — копи-паст, и надеетесь, что все будет работать по назначению!

Но сравните это с хорошо зарекомендовавшими себя проектами, которые имеют отличную документацию, и совершенно противоположный опыт. Например, документация API Stripe не только чиста и удобна для просмотра, для нее также реализован удобная навигация, и она аннотируется примерами на 8 разных языках относительно того, как правильно взаимодействовать с их API-интерфейсом разработчика. Хотите узнать, как создать новый клиент? Конечно! На каком языке вы хотите написать код?

Подобный уровень надежности становится необходимым при использовании огромных, публичных проектов, таких как платежи по Stripe, но может быть необязательным для ваших собственных или небольших проектов. Это не значит, что вы можете пренебречь документацией! Это просто означает, что наша цель при документировании личных проектов должна состоять в том, чтобы получить максимальную отдачу от каждого доллара. Способ, которым мы можем это сделать, — правильно комментировать наш код и использовать существующие в сообществе Javascript инструменты, чтобы предоставить понятную и полезную документацию с минимальными затратами сил и времени.

Документация API Stripe — это та-а-ак красиво …

Как создать сайт самому?

Какие технологии и знания необходимы сегодня, чтобы создавать сайты самостоятельно? Узнайте на интенсиве!

В этой статье мы поговорим о том, как использовать два разных инструмента, а именно JSDoc и Documentation.js, чтобы получить доступную, согласованную документацию на уровне API для вашего кода Javascript с минимальными усилиями. В студии 4Thought мы являемся поклонниками использования Flow, поэтому мы применим его, чтобы сделать вещи еще более понятными. Стремясь быть максимально полезными и краткими, мы не будем углубляться в полный синтаксис JSDoc, но стоит упомянуть, что документация THEIR (хотя и выглядит не очень красиво) хорошо читаема, и вам стоит потратить 20 минут или около того, чтобы ознакомиться с ней.

JSDoc

JSDoc — это стандартизированный способ написания комментариев в коде для описания функций, классов, методов и переменных в вашей базе кода. Если вы знакомы с JavaDocs или любыми его производными (например, доступными в PHP), то JSDocs будет вам понятен. Идея заключается в том, что мы описываем, как наш код работает с помощью нескольких специальных ключевых слов и конвенции форматирования, и мы можем использовать синтаксический анализатор для парсинга всего кода с комментариями и создания хорошей, читаемой документации, основанной на комментариях, которые мы пишем. Как это выглядит на практике? Вот краткий пример:

7 рекомендаций по оформлению кода на JavaScript

Автор материала говорит, что она прямо-таки одержима написанием чистого кода. Она считает, что код надо писать так, чтобы, во-первых, с ним, в будущем, удобно было бы работать другим программистам, включая его автора, а во-вторых — с учётом возможности расширения этого кода. То есть, нужно стремиться к тому, чтобы в приложение сравнительно просто было бы добавлять новые возможности, и чтобы его кодовую базу было бы удобно сопровождать. Если бы программы писали, учитывая лишь нужды компьютеров, то, вероятно, программисты могли бы выражать свои мысли лишь с помощью нулей и единиц, больше ни о чём не заботясь. В этой статье приводится ряд рекомендаций по написанию качественного кода, проиллюстрированных примерами на JavaScript.

1. Используйте понятные имена переменных и функций

Код гораздо легче читать, когда при его написании используют понятные, описательные имена функций и переменных. Вот не очень понятный код:

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

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

Мастер Йода рекомендует:  Аудит в XML-формате

2. Пишите короткие функции, решающие одну задачу

Функции легче поддерживать, они становятся гораздо более понятными, читабельными, если они направлены на решение лишь какой-то одной задачи. Если мы сталкиваемся с ошибкой, то, при использовании маленьких функций, найти источник этой ошибки становится гораздо легче. Кроме того, улучшаются возможности по повторному использованию кода. Например, вышеприведённой функции можно было бы дать имя sumAndAverageArray , так как в ней мы вычисляем сумму значений элементов массива, используя метод reduce , а затем находим среднее значение, деля полученную сумму на количество элементов массива. Вот эта функция.

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

Признаком того, что функцию можно разбить на две, является возможность использования слова «and» в её имени.

3. Документируйте код

Пишите хорошую документацию к своему коду — тогда тот, кто столкнётся с ним в будущем, поймёт, что и почему в этом коде делается. Вот пример неудачной функции. Здесь используются некие «магические числа», их смысл нигде не пояснён.

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

Этот код — всего лишь пример. Вероятно, в подобной ситуации, вместо введения собственной константы, хранящей число Пи, лучше будет воспользоваться стандартным свойством Math.PI .

Комментарии к коду должны отвечать на вопрос «почему».


Обратите внимание на то, что для целей документирования кода имеет смысл воспользоваться специальными инструментами и соответствующими им правилами комментирования кода. В применении к Python мне нравится Google Style Docstrings, в применении к JavaScript — JSDoc.

4. Подумайте об использований правил Сэнди Метц

Сэнди Метц отлично программирует на Ruby, делает интересные доклады и пишет книги. Она сформулировала четыре правила написания чистого кода в объектно-ориентированных языках. Вот они.

  1. Классы не должны быть длиннее 100 строк кода.
  2. Методы и функции не должны быть длиннее 5 строк кода.
  3. Методам следует передавать не более 4 параметров.
  4. Контроллеры могут инициализировать лишь один объект.

Рекомендую посмотреть её выступление, касающееся этих правил.

Я следую этим правилам уже примерно два года, и они так основательно закрепились в моём сознании, что я выполняю их, буквально, «на автомате». Мне они нравятся, и я полагаю, что благодаря их использованию повышается удобство сопровождения кода.

Обратите внимание на то, что данные правила — это лишь рекомендации, но их использование позволит сделать ваш код значительно лучше.

5. Применяйте выбранные правила последовательно

Последовательное применение правил написания кода очень важно независимо от того, пишете ли вы код некоего проекта самостоятельно или работаете в команде. В частности, выражается это в том, что тот, кто читает код, являющийся результатом командной разработки, должен воспринимать его как единое целое. При таком подходе авторство отдельных строк кода можно установить, лишь обратившись к Git. Если вы, в JavaScript, используете точку с запятой — ставьте её везде, где это нужно. То же самое касается и кавычек — выберите двойные или одинарные кавычки и, если на то нет веских причин, всегда используйте то, что выбрали.

Рекомендую применять руководство по стилю кода и линтер, который позволяет приводить код к выбранному стандарту. Например, мне, для JavaScript, нравятся правила Standard JS, для Python — правила PEP8.

На самом деле, главное здесь — найти правила оформления кода и их придерживаться.

6. Помните о принципе DRY

Одна из первых идей, которую стараются донести до того, кто хочет стать программистом, звучит так: «не повторяйся» (Don’t Repeat Yourself, DRY). Если вы замечаете в своих проектах повторяющиеся фрагменты — используйте такие программные конструкции, которые позволят сократить повторы одного и того же кода. Я часто советую моим ученикам поиграть в игру SET для того, чтобы улучшить их навыки по распознаванию шаблонов.

Однако если вы приметесь фанатично применять принцип DRY или решите абстрагировать неудачно выбранные шаблоны, читаемость кода может серьёзно ухудшиться, и, позже, вам может понадобиться чаще прибегать к созданию копий одних и тех же конструкций. У Сэнди Метц, кстати, есть отличная статья, посвящённая тому, что дублирование кода — это меньшее зло, нежели неудачная абстракция.

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

7. Используйте идеи инкапсуляции и модульности

Группируйте связанные переменные и функции для того, чтобы сделать ваш код понятнее и улучшить его с точки зрения его повторного использования. Вот пример не самого удачно организованного кода, в котором сведения о человеке оформлены в виде отдельных переменных.

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

А если в программе надо работать лишь с данными об одном человеке, то их можно оформить так, как показано ниже.

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

Итоги

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

Смартсорсинг.ру

Сообщество руководителей ИТ-компаний, ИТ-подразделений и сервисных центров

участников являются сотрудниками ИТ-компаний

20% из них — совладельцы бизнеса

работают в ИТ-службах других компаний

Войти с помощью:


Авторизация

Новым пользователям

Зачем?

Мастер-класс: «Понимание чужого кода на примере JavaScript», 17 февраля 2015 года

Дата: 17 февраля, 19:30

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

Зачем понимать чужой код?
Потому что веб-разработчик:

  • повысит скорость исследования кода и решения задач;
  • даст максимально верную оценку на выполнение задачи;
  • определит смысл раннее написанного кода;
  • совершенствуется и сможеть дать советы другим разработчикам по написанию кода.

На встрече поговорим о:
— проблемах при ревью чужого кода и их решениях;
— почему со временем код становится трудным для чтения, и как этого избежать;
— разберем конкретные шаблоны сложного для понимания кода (спагетти-код, костыли, велосипеды).

15 советов по написанию самодокументируемого кода (на примере JavaScript)

Частная коллекция качественных материалов для тех, кто делает сайты

  • Фотошоп-мастер2000+ уроков по фотошопу
  • Фото-монстр300+ уроков для фотографов
  • Видео-смайл200+ уроков по видеообработке
  • Жизнь в стиле «Кайдзен» Техники и приемы для гармоничной и сбалансированной жизни
  • Главная»
  • Уроки»
  • Уроки jQuery для начинающих

В этой рубрике Вы найдете уроки по Javascript библиотеке jQuery.

Анимация набора текста на jQuery

Сегодня мы бы хотели вам рассказать о библиотеке TypeIt — бесплатном jQuery плагине. С её помощью можно имитировать набор текста. Если всё настроить правильно, то можно добиться очень реалистичного эффекта.

Временная шкала на jQuery

jQuery плагин для создания временной шкалы.

Заметка: Перезагрузка и редирект на JavaScript

Быстрая заметка, где вы сможете найти парочку JS сниппетов для перезагрузки и перенаправления пользователей через JavaScript.

Рисуем диаграмму Ганта

jQuery плагин для создания диаграммы Ганта.

AJAX и PHP: загрузка файла

Пример того как осуществить загрузку файла через PHP и jQuery ajax.

Stimed — стили в зависимости от времени суток

Интересная библиотека с помощью которой можно задать определённым элементам страницы особые стили в зависимости от времени суток.

jQuery плагин для отображения превью загружаемого файла

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

Добавить комментарий