Poradnik stylu Blockly

Stosuj styl Google TypeScript .

Migracja do TypeScript & ES6

Pierwotnie Blockly zostało napisane w języku ES5.1 zgodnie z starszą, obowiązującą wówczas wersją przewodnika po stylu JavaScriptu Google. Nowo napisany kod powinien być zgodny z aktualnym przewodnikiem po stylu i wykorzystywać funkcje języka ES6, takie jak let, const, class, a także przypisanie destrukturyzujące, gdy jest to właściwe. Dotychczasowy kod może zostać zaktualizowany lub może być niezgodny z zasadami. Zespół Blockly stara się podjąć najlepszą decyzję, biorąc pod uwagę spójność kodu i dla użytkowników biblioteki – na przykład możemy zrezygnować z zmiany nazwy funkcje publiczne, które nie są już zgodne ze wskazówkami redakcyjnymi.

Tak

  • Użyj narzędzi lintowania i formatowania.
    • Używamy eslint i mamy .eslintrc.jsplik skonfigurowany z regułami preferowanego stylu.
    • Do automatycznego formatowania używamy prettier.
    • Uruchom npm run lint, aby uruchomić lintera, a npm run format, aby uruchomić narzędzie do formatowania.
  • Dodaj wcięcia – spacje, a nie znaki tabulacji.
  • Używaj średników.
  • W polu camelCase używaj zmiennych i funkcji.
  • Używaj TitleCase na potrzeby zajęć.
  • Do stałych wartości używaj ALL_CAPS.
  • Używanie nawiasów klamrowych dla wszystkich struktur sterujących.
    • Wyjątek: w przypadku instrukcji if na jednej linii możesz pominąć nawiasy klamrowe.
  • Używaj pojedynczych cudzysłowów (oprócz zapisu w formacie JSON).
  • Ponowne deklarowanie zmiennych w pętlach for. Oznacza to, że zawsze należy pisać for (const i = 0; ...) zamiast for (i = 0; ...).
    • W przeciwnym razie istnieje ryzyko, że po przerefaktoryzowaniu funkcji na wyższym poziomie zmienna stanie się porzucona i niespodziewanie stanie się zmienną globalną.
  • Komentarze muszą zaczynać się wielką literą, a kończyć kropką.
  • Twórz zgłoszenia na GitHubie z TODO i łącz je za pomocą TODO(#issueNumber).
  • Dodawaj adnotacje do wszystkiego za pomocą TSDoc.

Nie

  • Dodaj wcięcie do tabulatorów.
  • Używaj podkreśleń na końcu nazw zmiennych lub funkcji.
    • Niektóre starsze wersje kodu używają znaku podkreślenia w przypadku prywatnych lub wewnętrznych właściwości i funkcji. Mogą one wciąż istnieć, ale nie należy tworzyć żadnego nowego kodu. dodane zgodnie z tą konwencją.
  • Użyj konta snake_case.
  • Używaj podwójnych cudzysłowów (chyba że używasz kodu JSON).
  • Użyj uszkodzonego pliku TSDoc.
    • Nasz dokument TSDoc jest automatycznie publikowany jako część naszej dokumentacji.
  • Wpisz TODO (username).
    • Zamiast tego utwórz na GitHubie problemy 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.

TSDoc

Zespół Blockly dodaje adnotacje do kodu za pomocą TSDoc wygenerować dokumentację. Oczekujemy pliku TSDoc dla wszystkich publicznych właściwości klas oraz dla wszystkich wyeksportowanych funkcji.

Aby komentarze w dokumencie TSDoc zostały prawidłowo przeanalizowane, muszą zaczynać się od /** i kończyć ciągiem */.

Typy

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

Widoczność

Funkcje lub właściwości, do których dostęp jest możliwy tylko w bibliotece Blockly powinien być oznaczony w adnotacji @internal. Zapobiega to wyświetlaniu tych właściwości w publicznej dokumentacji. Inne modyfikatory widoczności należy umieszczać bezpośrednio w kodzie TypeScript, a nie w TSDoc.

Właściwości

Dokument TS dotyczący właściwości powinien zawierać opis właściwości. Opis może zostać pominięty ze względu na właściwości, które nie wymagają wyjaśnienia.

/**
  *   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 do funkcji powinny zawierać

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

Opisów funkcji, parametrów i wartości zwracanych można pominąć, jeśli są one oczywiste.

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