Przewodnik stylistyczny

Postępuj zgodnie ze Style Guide TypeScript firmy Google.

Migracja do TypeScript i 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 oraz przypisanie destrukturyzujące (w odpowiednich przypadkach). Istniejący kod może zostać zaktualizowany lub może nie być zgodny z wymaganiami. Zespół Blockly stara się podejmować najlepsze decyzje, biorąc pod uwagę spójność kodu i wrażenia użytkowników biblioteki. Możemy na przykład nie zmieniać nazwy funkcji publicznych, które nie są już zgodne z przepisami przewodnika stylów.

Tak

  • Używanie narzędzi do sprawdzania kodu i formatowania.
    • Używamy eslint i mamy plik eslint.config.mjsskonfigurowany z regułami preferowanego stylu.
    • Do automatycznego formatowania używamy prettier.
    • Uruchom npm run lint, aby uruchomić linter, i npm run format, aby uruchomić formatowanie.
  • Użyj spacji, a nie tabulacji.
  • Użyj przecinków.
  • Do zmiennych i funkcji używaj znaku camelCase.
  • Użyj TitleCase do zajęć.
  • Do stałych wartości używaj ALL_CAPS.
  • Używaj nawiasów klamrowych do wszystkich struktur sterujących.
    • Wyjątek: w przypadku instrukcji if na jednej linii możesz pominąć nawiasy.
  • Użyj cudzysłowów (z wyjątkiem kodu JSON).
  • Ponowne deklarowanie zmiennych w pętlach for. Oznacza to, że zawsze należy pisać for (const i = 0; ...) zamiast for (i = 0; ...).
    • Jeśli tego nie zrobisz, 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ą.
  • Tworzenie zgłoszeń na GitHub z TODO i ich łączenie za pomocą TODO(#issueNumber).
  • Dodawaj adnotacje do wszystkiego za pomocą TSDoc.

Nie

  • wcięcie za pomocą tabulatorów;
  • Używaj podkreślenia na końcu nazw zmiennych lub funkcji.
    • Niektóre starsze wersje kodu używają znaków podkreślenia w przypadku właściwości lub funkcji prywatnych bądź wewnętrznych. Chociaż te reguły mogą nadal obowiązywać, nie należy dodawać nowego kodu zgodnie z tymi zasadami.
  • Użyj konta snake_case.
  • Użyj podwójnych cudzysłowów (z wyjątkiem sytuacji, gdy piszesz kod JSON).
  • Używanie zniekształconego dokumentu TSDoc.
    • Dokument TSDoc jest automatycznie publikowany w ramach naszej dokumentacji.
  • Zapis: TODO (username).
    • Zamiast tego twórz problemy w GitHub z TODO i łącz je za pomocą TODO(#issueNumber).
  • Użyj konta string.startsWith. Zamiast tego użyj Blockly.utils.string.startsWith.

TSDoc

Zespół Blockly używa narzędzia TSDoc do adnotowania kodu i generowania dokumentacji. Oczekujemy pliku TSDoc dla wszystkich publicznych właściwości klas oraz wszystkich wyeksportowanych funkcji.

Aby komentarze TSDoc zostały poprawnie przeanalizowane, muszą zaczynać się od /** i kończyć */.

Typy

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

Widoczność

Funkcje lub właściwości, do których dostęp powinien być możliwy tylko w bibliotece Blockly, powinny być opatrzone adnotacją @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 pliku TSDoc.

Właściwości

TSDoc dla usług powinien zawierać opis usługi. Opis może zostać pominięty w przypadku właściwości, które są jasne bez dodatkowych 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
  • Jeden tag @param na parametr, w tym:
    • Nazwa
    • Opis
  • Tag @returns, jeśli funkcja zwraca wartość, wraz z opisem tej 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;
}