Руководство по блочному стилю

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

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

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

Делать

  • Используйте инструменты линтинга и форматирования.
    • Мы используем eslint , и у нас есть файл .eslintrc.js с правилами для предпочитаемого нами стиля.
    • Мы используем prettier для автоматического форматирования.
    • Запустите npm run lint , чтобы запустить линтер, и 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 .

ТСДок

Команда 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;
}