Dobre praktyki ScriptCode

Kontekst

Reguły dotyczące pisania ScriptCode na platformie Eximee pozwolą zapewnić spójność, czytelność oraz bezpieczeństwo kodu, a także ułatwią wdrożenie nowych pracowników.

Twórz ScriptCode zgodnie z regułami opisanymi poniżej.

Obszar	Reguła
Spójna konwencja nazewnicza	Pisz kod w języku angielskim - stosuj angielskie nazwy zmiennych, funkcji itp. Wyjątki: odgórne ustalenia biznesowe dotyczące nazewnictwa lub duży poziom skomplikowania skryptu (tu decyzja należy do low-code developera). Jeśli decydujesz się na konwencję nazw po polsku - bądź spójny w obrębie jednego skryptu. Stałe literalne wpisane na sztywno w kodzie nazywaj w formacie UPPER_SNAKE_CASE, np. const MOBILE_CHANNEL = "mobile" Pozostałe zmienne i funkcje nazywaj w formacie camelCase, np. const correlationId = context.getFirstParameter('correlationId'), let motherBranchNumber, function generateBranch()
Kolejność w strukturze kodu	Kod organizuj zgodnie z poniższą kolejnością: Stałe literalne- deklaruj na początku skryptu Zmienne - następnie deklaruj zmienne, które będą używane w logice głównej Logika główna - główny ciąg operacji, które kod wykonuje (np. przetwarzanie danych, wywoływanie funkcji) Funkcje pomocnicze - umieszczaj na końcu
Logowanie	Nie duplikuj logów platformowych - jeśli jakieś parametry są automatycznie generowane przez platformę nie loguj ich ponownie w skrypcie Używaj loggera sensytywnego do logowania danych wrażliwych, wzór: Logger.info("Pesel klienta wypełniony na formularzu: {}", pesel) Dowiedz się więcej: Logowanie w ScriptCode
Deklaracja zmiennych	Nie używaj varów Typy prymitywne: używaj let tylko gdy zmieniasz w skrypcie wartość zmiennej. W pozostałych przypadkach używaj const Typy złożone: nie używaj let jeśli modyfikujesz tylko zawartość obiektu - w tym tablic (Array), setów (Set), map (Map). Nie ma potrzeby używania let przy deklarowaniu obiektów - w tym tablic (Array), setów (Set), map (Map) - o ile referencja (czyli odwołanie do konkretnego obiektu lub tablicy) nie będzie zmieniana. W większości przypadków powinno się stosować const do deklarowania tablic i innych obiektów, nawet jeśli ich zawartość będzie modyfikowana. Przykład z użyciem const: const array = [1, 2, 3]; array.push(4); // Działa poprawnie, modyfikujemy zawartość tablicy const obj = { name: "Alice" }; obj.age = 30; // Działa poprawnie, modyfikujemy właściwości obiektu Uwaga: Dopóki silnik rhino nie wspiera poprawnie zakresu blokowego dla const należy wewnątrz pętli "for" deklarować zmienne z wykorzystaniem let. Więcej o błędzie można przeczytać w materiale podlinkowanym poniżej. Dowiedz się więcej: Typy danych w Javascript, Referencja, mutowalność, typy prymitywne - powtórka Javascript! Skrypty(ScriptService) Tabela z wykazem które funkcjonalności nie są obecnie poprawnie wspierane przez silnik rhino Rhino: błąd przy deklaracji const wewnątrz pętli for
Obsługa błędów	Używaj bloków try-catch w miejscach, gdzie mogą wystąpić wyjątki. W razie wystąpienia błędu, loguj go z użyciem loggera, aby umożliwić łatwe śledzenie problemu.
Czytelność kodu	Kliknij prawy przycisk myszy → wybierz Format Document. Dzięki temu kod będzie bardziej przejrzysty i czytelny Usuwaj kod, który jest zakomentowany i już niepotrzebny Pisz komentarze w sposób zwięzły i jasny, wyjaśniając trudniejsze fragmenty kodu, intencje i nietypowe rozwiązania. Unikaj oczywistych komentarzy, które jedynie powtarzają to, co jest już czytelne w kodzie.
Powtarzalność kodu	Jeśli powtarzasz kilka razy fragment kodu - stwórz funkcję pomocniczą
Opis skryptu	Tworząc nowy skrypt/walidator - dodaj opis
Testy	Twórz testy jednostkowe zawsze gdy jest to możliwe, uwzględniaj warunki brzegowe.
Bezpieczeństwo	Wszelkie parametry wchodzące do ScriptCode'u traktuj jako niezaufane przy wysyłaniu do usług Przykładowy kod: Źle: Dobrze: Nie używaj danych autoryzacyjnych bezpośrendio w ScriptCode Pobieraj zdalne zasoby (obrazki, dokumenty, wizerunki kart itd. ) z zaufanego źródła (np. platforma eximee, zasób bankowy) Jeżeli musisz użyć w aplikacji jakikolwiek link upewnij się, że jest zaufany a jego użycie wynika wprost z wymagań Jeżeli jakiejś funkcjonalności nie ma w platformie to zgłoś zapotrzebowanie - nie korzystaj z zewnętrznych narzędzi Dowiedz się więcej: OWASP_Application_Security_Verification_Standard_4.0 - scriptCode
Operacje matematyczne z BigDecimal	Operacje matematyczne przeprowadzaj z wykorzystaniem z BigDecimal Dowiedz się więcej: Operacje matematyczne w ScriptCode
Obsługa wartości falsy	Przed użyciem właściwości lub metod sprawdź, czy wartość zmiennej nie jest null ani undefined, aby zapobiec błędom związanym z brakiem wartości. W sytuacjach, gdy chcesz wychwycić również 0, pusty string lub NaN, możesz stosować ogólny warunek if(value).
Review	Jeśli nie jesteś jedynym low-code developerem w zespole - poproś kogoś z teamu o review kodu.

Materiały

• OWASP_Application_Security_Verification_Standard_4.0 - scriptCode
• Operacje matematyczne w ScriptCode