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, inpm run format
, aby uruchomić formatowanie.
- Używamy eslint i pliku
- 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
.
- Wyjątek: możesz pominąć nawiasy w jednowierszowych wyrażeniach
- Używaj cudzysłowów pojedynczych (chyba że zapisujesz pliki JSON).
- Ponownie zadeklaruj zmienne w pętlach
for
. Oznacza to, że zawsze zapisujfor (const i = 0; ...)
zamiastfor (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)
.
- Zamiast tego utwórz problemy z GitHub z zadaniami do wykonania i połącz je za pomocą
- Użyj konta
string.startsWith
. Użyj w zamian zasadyBlockly.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;
}