Poradnik stylu Blockly

Postępuj zgodnie ze wskazówkami dotyczącymi stylów w Google TypeScript.

Migracja do TypeScriptu i ES6

Blockly został pierwotnie napisany w języku ES5.1 zgodnie z starszą, w dotychczasową wersją przewodnika Google po stylu JavaScript. Nowo napisany kod powinien być zgodny z bieżącym przewodnikiem stylu i w stosownych przypadkach używać funkcji języka ES6 (takich jak let, const czy class). Istniejący kod może zostać zaktualizowany lub może nie być zgodny z zasadami. Zespół Blockly próbuje podjąć najlepszą decyzję, biorąc pod uwagę spójność kodu i wygodę użytkowników biblioteki. Na przykład możemy zdecydować się nie zmieniać nazw funkcji publicznych, które nie są już zgodne z naszymi wskazówkami.

Tak

  • Korzystaj z narzędzi do lintowania i formatowania.
    • Używamy eslint i pliku .eslintrc.js z regułami dla preferowanego stylu.
    • Do automatycznego formatowania używamy ładniejszego.
    • Uruchom npm run lint, aby uruchomić linter, i npm run format, aby uruchomić formatowanie.
  • Dodaj wcięcie za pomocą spacji, a nie tabulatorów.
  • Używaj średników.
  • Użyj właściwości camelCase dla zmiennych i funkcji.
  • Używaj na zajęciach TitleCase.
  • Jako wartości stałych użyj ALL_CAPS.
  • Użyj nawiasów klamrowych we wszystkich strukturach kontrolnych.
    • Wyjątek: możesz pominąć nawiasy w jednowierszowych wyrażeniach if.
  • Używaj cudzysłowów pojedynczych (chyba że zapisujesz pliki JSON).
  • Ponownie zadeklaruj zmienne w pętlach for. Oznacza to, że zawsze zapisuj for (const i = 0; ...) zamiast for (i = 0; ...).
    • W przeciwnym razie istnieje ryzyko, że po refaktoryzacji na wyższym poziomie funkcji zmienna zostanie osierocona i stanie się niespodziewaną globalnie.
  • Zacznij komentarz od wielkich liter i kończ je kropkami.
  • Utwórz problemy z GitHub z zadaniami do wykonania i połącz je za pomocą usługi TODO(#issueNumber).
  • Dodaj adnotacje do wszystkiego w TSDoc.

Nie

  • Wcięcie przy użyciu tabulatorów.
  • Podkreślaj na końcu nazw zmiennych lub funkcji.
    • Niektóre wcześniejsze fragmenty kodu używają podkreśleń w usługach i funkcjach prywatnych lub wewnętrznych. Mogą one nadal istnieć, ale zgodnie z tą konwencją nie należy dodawać nowego kodu.
  • Użyj konta snake_case.
  • Używaj cudzysłowów podwójnych (chyba że zapisujesz pliki JSON).
  • Użyj uszkodzonego TSDoc.
    • Ten dokument TSDoc jest automatycznie publikowany jako część naszej dokumentacji.
  • Napisz tekst TODO (username).
    • Zamiast tego utwórz problemy z GitHub z zadaniami do wykonania i połącz je za pomocą TODO(#issueNumber).
  • Użyj konta string.startsWith. Użyj w zamian zasady Blockly.utils.string.startsWith.

Dokument rozwiązywania problemów

Zespół Blockly używa TSDoc do dodawania adnotacji do kodu i generowania dokumentacji. Oczekujemy, że TSDoc będzie dotyczyć wszystkich publicznych właściwości klas i wszystkich wyeksportowanych funkcji.

Aby komentarze były prawidłowo analizowane, muszą zaczynać się od /** i kończyć na */.

Typy

Typy są pomijane w TSDoc, ponieważ informacje te znajdują się bezpośrednio w kodzie TypeScript. Jeśli edytujesz jeden z niewielu pozostałych plików JavaScript, dodaj adnotacje typu zgodnie z dokumentacją narzędzia Closure Compiler.

Widoczność

Funkcje lub właściwości, do których chcesz mieć dostęp tylko w bibliotece Blockly, powinny mieć adnotację @internal. Dzięki temu właściwości te nie pojawią się w publicznej dokumentacji. Inne modyfikatory widoczności należy umieszczać bezpośrednio w kodzie TypeScript, a nie w TSDoc.

Właściwości

TSDoc dotyczący usług powinien zawierać opis właściwości. Opis może zostać pominięty w przypadku właściwości niewymagających wyjaśnień.

/**
  *   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);

Funkcje

Adnotacje funkcji powinny zawierać

  • Opis funkcji
  • Po 1 tagu @param na parametr, w tym:
    • Nazwa
    • Opis
  • tag @returns, jeśli funkcja zwróci wartość z opisem zwróconej wartości.

Opisy funkcji, parametrów lub zwracanych wartości mogą być pomijane, jeśli nie trzeba ich objaśniać.

Na przykład:

/**
 *   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;
}