Руководство по стилю

Следуйте руководству по стилю Google TypeScript .

Миграция на TypeScript и ES6

Blockly изначально был написан на ES5.1 в соответствии с более старой, тогда актуальной версией руководства по стилю Google JavaScript . Новый код должен соответствовать текущему руководству по стилю и использовать такие возможности языка ES6, как let , const , class , destructuring assignment , где это применимо. Существующий код может быть обновлен или может быть исключен из соответствия. Команда Blockly старается принять наилучшее решение, принимая во внимание согласованность кода и опыт пользователей библиотеки — например, мы можем решить не переименовывать публичные функции, которые больше не соответствуют руководству по стилю.

Делать

  • Используйте инструменты линтинга и форматирования.
    • Мы используем eslint и настроили файл eslint.config.mjs с правилами для нашего предпочтительного стиля.
    • Для автоматического форматирования мы используем prettier .
    • Запустите npm run lint для запуска linter и npm run format для запуска форматтера.
  • Отступы делайте пробелами, а не табуляциями.
  • Используйте точку с запятой .
  • Используйте camelCase для переменных и функций.
  • Используйте TitleCase для классов.
  • Для констант используйте ALL_CAPS .
  • Используйте скобки для всех управляющих конструкций.
    • Исключение: для однострочных операторов if можно опустить фигурные скобки.
  • Используйте одинарные кавычки (за исключением случаев написания JSON).
  • Переопределите переменные в циклах for . То есть всегда пишите for (const i = 0; ...) вместо for (i = 0; ...) .
    • Невыполнение этого требования повышает риск того, что после рефакторинга выше в функции переменная станет «сиротой» и неожиданно станет глобальной.
  • Начинайте комментарии с заглавных букв и заканчивайте точками.
  • Создавайте задачи на GitHub с помощью TODO и связывайте их с помощью TODO(#issueNumber) .
  • Аннотируйте все с помощью TSDoc .

Не

  • Отступ с помощью табуляции.
  • Используйте подчеркивание в конце имен переменных или функций.
    • В некоторых ранних кодах используются подчеркивания для частных или внутренних свойств или функций. Хотя они могут продолжать существовать, не следует добавлять новый код, следуя этому соглашению.
  • Используйте snake_case .
  • Используйте двойные кавычки (за исключением случаев написания JSON).
  • Использовать некорректный TSDoc.
    • Наш TSDoc автоматически публикуется как часть нашей документации.
  • Напишите TODO (username) .
    • Вместо этого создавайте задачи на GitHub с помощью TODO и связывайте их с помощью TODO(#issueNumber) .
  • Используйте string.startsWith . Вместо этого используйте Blockly.utils.string.startsWith .

TSDoc

Команда Blockly использует TSDoc для аннотирования нашего кода и создания документации. Мы ожидаем TSDoc для всех публичных свойств классов и для всех экспортируемых функций.

Комментарии TSDoc должны начинаться с /** и заканчиваться */ для корректного анализа.

Типы

Типы опущены из TSDoc, поскольку эта информация находится непосредственно в коде TypeScript. Если вы редактируете один из немногих оставшихся файлов JavaScript, включите аннотации типов в соответствии с документацией Closure Compiler .

Видимость

Функции или свойства, доступ к которым должен осуществляться только в библиотеке Blockly, должны быть аннотированы @internal . Это предотвращает появление этих свойств в публичной документации. Другие модификаторы видимости должны быть размещены непосредственно в коде TypeScript, а не в TSDoc.

Характеристики

TSDoc для свойств должен включать описание свойства. Описание может быть опущено для самообъясняющих свойств.

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

Функции

Аннотации к функциям должны включать

  • Описание функции
  • Один тег @param на параметр, включая
    • Имя
    • Описание
  • Тег @returns , если функция вернет значение, с описанием возвращаемого значения.

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

Например:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}