Ocena małego projektu JS (Node.js) + Bash

Odpowiedz Nowy wątek
2019-07-17 21:54
1

Chciałbym poprosić Was o ocenę mojego niedawno rozpoczętego projektu z logiką w JavaScript w Node.js i z interfejsem CLI w Bashu:

https://github.com/silvuss/silvuss-bracket-string-validator

Projekt jest niewielki, jego funkcjonalność jest znikoma (zresztą przeczytajcie README). Niemniej pokładam w nim dwie nadzieje:

  • stanie się kiedyś wizytówką mnie dla samego siebie; co przez to rozumiem? między innymi: będzie dobrze wypozycjonowany, będzie mieć dobrze wymyśloną architekturę, dobrze napisany kod i dokumentację, ukończone wszystkie issues, zrozumiałe commit messages i naprawione wszystkie błędy, jakie można w nim znaleźć (pomijając rzeczy niezależne ode mnie, np. pewne niezbyt trafne konstrukcje języków);
  • będę mógł podpiąć pod niego – jako GUI – interfejs w Angularze; dzięki temu moja nauka podstaw Angulara pójdzie do przodu; obecnie jest jakby zamrożona.

Zależy mi na ocenie całego projektu na GutHubie (nie tylko aplikacji). M.in. chodzi mi o ocenę następujących rzeczy:

  • wydań – czy opisy są zrozumiałe; może dobrze będzie dołączać jakieś pliki, może cały projekt w innym formacie niż obecnie (obecnie jest tylko skompresowany kod źródłowy);
  • issues – szczególnie istotne; czy są dobrze wydzielone, czy nie za dużo / za mało;
  • architektury, w tym obsługi błędów – szczególnie istotne; do poprawy, ale nie mam za bardzo pomysłów, więc chętnie poznam jakiekolwiek sugestie;
  • kodu, w tym komentarze – podział na funkcje, pliki, czytelność, zwięzłość/rozwklekłość, nazwy zmiennych itd.;
  • dokumentacji – szczególnie istotne; np. czy jest czytelna i zrozumiała, czy nie za długa, czy czegoś w niej nie brakuje;
  • czy logika jest w odpowiednim miejscu; może np. trzeba przenieść część z CLI do logiki, a może część z logiki do CLI;
  • czy struktura katalogów w projekcie jest w porządku (jest moja – nie sugerowałem się niczym konkretnym).

Z racji niewielkiego rozmiaru projektu (nie bardzo może być co krytykować :P) najbardziej proszę w powyższych punktach o wskazówki dotyczące wzorców projektowych, które mógłbym użyć, metodologii, bibliotek, frameworków oraz co jeszcze mógłbym dodać jako funkcjonalność do tego projektu. Nowa funkcjonalność powinna być jakoś powiązana ze starą; w tym projekcie nie zależy mi na robieniu aplikacji, która pierze, sprząta i gotuje.

Jak zwykle – wszelkie sugestie są mile widziane. :) W tym – literówki i błędy w dokumentacji czy w komentarzach (tym bardziej, że są po angielsku).

Postaram się tutaj opisywać zmiany w projekcie, dopóki wszystkich sugestii nie rozpatrzę.


Na koniec, korzystając z okazji, chciałbym podziękować dwóm osobom:

  • użytkownikowi @Mr.YaHooo za umieszczenie na naszym forum pierwszej wersji algorytmu sprawdzającego, czy ciąg znaków jest wyrażeniem nawiasowym w tym poście;
  • użytkowniczce @Kate321 za założenie tego wątku; dzięki temu w ogóle poznałem ideę wyrażeń nawiasowych. Trochę szkoda, że już nie wchodzi na forum. @Kate321, jeśli to czytasz, napisz proszę.

UPDATE 19 lipca 2019: Dodałem w projekcie komentarze JSDoc (jak ktoś zna Javę – Wikipedia określa je jako podobne do komentarzy Javadoc). Tutaj wydanie, które to opisuje: https://github.com/silvuss/si[...]validator/releases/tag/v1.1.0


UPDATE 28 lipca 2019: Kolejne, duże, wydanie mojej aplikacji: 1.2.0 (link). Dodałem testy jednostkowe; wykorzystuję przy nich frameworki Mocha oraz Jest. Z innych zmian – nareszcie włączyłem wsparcie dla usługi Travis CI.


edytowany 10x, ostatnio: Silv, 2019-07-28 03:19
Pokaż pozostałe 5 komentarzy
@Silv: Istnieje też coś takiego w psychologii co nazwałbym roboczo "todo trap" (nie pamiętam fachowej nazwy), sam się na tym złapałem kilka razy - czyli sam proces tworzenia sprawia (taski, docs itp.) nam więcej przyjemności niż samo tworzenie (pisanie właściwego kodu) np. oznaczanie tasku jako done daje nam trochę endorfiny i z czasem robimy coraz więcej łatwych tasków żeby je oznaczać jako done - jest o tym trochę więcej w książce "Getting Things Done, czyli sztuka bezstresowej efektywności" (której nie polecam, bo jest nudna) - finalnie projekt rozwija się coraz wolniej. - Markuz 2019-07-18 12:40
@no_solution_found: nazwę silvuss (czyli nazwę pierwotną do Silv, takie coś jakby podawanie argumentów w konsoli w formie --argument zamiast -a ;) ) podaję w przypadku każdego swojego repozytorium. Robię to z dwóch powodów: 1) by było wiadomo, czyje jest repozytorium (np. po sforkowaniu raczej to ktoś zmieni), i nie było nieporozumień; 2) by uspójnić proces rozwoju własnych projektów. - Silv 2019-07-18 16:00
PS. @no_solution_found: własną nazwę nadałem w ogóle w celu uproszczenia pisania skryptu – $1 mówi mi jeszcze mniej. Myślę, że jest to dobra praktyka w przypadku skryptów konsolowych. Dopóki nie przetwarzam argumentów w pętli używając np. shift po pobraniu każdego z nich, to istotne jest zachować poprawną ich kolejność. Dałoby się zmienić nazwy na inne, niepowiązane z kolejnością. Jednak w ten sposób kolejność argumentów byłaby zdefiniowana tylko w miejscu ich pobierania, a to dla mnie chyba trochę za mało. - Silv 2019-07-18 16:05
PS2. @no_solution_found: z Angularem – właśnie napisałem w tym poście, że będę kontynuować. :) Tylko muszę mieć odpowiedni kod, który będę mógł wykorzystać do niego. Taki, żeby coś robił, a z drugiej strony żeby nie zaciemniał mi samego Angulara. Myślę, że ta aplikacja się nada, tylko muszę jakoś ogarnąć kwestie marketingowe na początek (=ważniejsze niż funkcjonalność), np. Travisa CI. - Silv 2019-07-18 16:07
PS3. @Markuz: to może być. Ciekawe. Sam nad podobną kwestią rozmyślałem niedawno. Ja mam cel większy niż ten projekt (ho, ho), ale muszę jakoś podnieść swoją motywację w czasie tworzenia. Postaram się, by rozwój był na tyle dynamiczny, na ile funkcjonalność tej aplikacji pozwoli... no, i moje umiejętności devopsa-marketingowca (których nie posiadam). - Silv 2019-07-18 16:11

Pozostało 580 znaków

2019-07-19 18:53
0

Ty piszesz, że nie powinienem. Odpaliłem w Dockerze - docker jest odizolowany, mogę tam nawet rm -rf --no-preserve-root / odpalić bez szkody dla własnego komptera.

Pozostało 580 znaków

2019-07-19 19:24
0

A, odnosisz się do mojego README. ;) Tak, rzeczywiście napisałem w ten deseń, ale pozwolisz, że podam dokładny cytat:

This application is an example application that is not intended to be run. Its purpose is only to show code that is known to work. While probably nothing dangerous would happen, you may run it only under your own responsibility.

Mam na myśli tutaj, że nie rekomenduję żadnego bezpiecznego środowiska do uruchomienia tej aplikacji. Ponieważ ludzie są omylni, tak więc wskazywanie (np. przeze mnie) konkretnych zewnętrznych środowisk do uruchamiania konkretnych moich aplikacji byłoby obarczone pewnym błędem. Jest on dla mnie za duży do przyjęcia. Aby go uniknąć, ograniczam ryzyko do minimum. Uważam, że to, co napisałem, zgadza się z tym, czego sam potrzebuję jako twórca aplikacji.

Powyżej ograniczam margines błędu do świadomego wyboru użytkownika. W przypadku tej aplikacji rekomenduję ograniczenie marginesu błędu jeszcze bardziej – do uruchamiania w tym samym środowisku, co i ja. Pro forma zacytuję README:

Info: It is adviced to run this application in the same environment as it has been tested. In case of other environments this application may work properly, or its usage may cause unknown side effects, or it may not work at all.


UPDATE: I prawdopodobnie będę dodawać takie ograniczenia jak to drugie w przypadku każdej mojej aplikacji, która będzie zawierać skrypty powłoki.


edytowany 2x, ostatnio: Silv, 2019-07-19 19:26

Pozostało 580 znaków

2019-07-19 22:02
0

@Maciej Cąderek: przeczytałem dwa artykuły o Dockerze i nie wydaje mi się, żeby był istotny dla mojego dewelopmentu, przynajmniej w tej chwili. Jeśli miałbyś jakieś wskazówki odnośnie tego, czy i kiedy będę mógł go użyć przy tej aplikacji, to chętnie.

W tej chwili, z rzeczy przyszłych – bardziej widziałbym wirtualizację na poziomie systemu operacyjnego. Przyda się, kiedy będę wprowadzać kompatybilność z różnymi systemami. Na podstawowym poziomie, mam nadzieję, zostanie to zapewnione przez Travis CI.


UPDATE: Gdyby bardziej zaawansowany poziom konfiguracji był potrzebny, zawsze mogę spróbować postawić u siebie wirtualkę. Słyszałem o darmowych z Windowsem. Nie wiem nic o wirtualizacji urządzeń mobilnych. Trochę mnie martwi MacOS, gdybym go planował; albo mogę odpuścić go w ogóle, albo spróbować coś innego niż Travis. A może wtedy już aplikacja się tak rozrośnie, że będzie sama na siebie zarabiać = będę mógł zacząć na nią wydawać pieniądze? <zastanawia się>

Ale to pieśń przyszłości dalszej niż ten miesiąc.


edytowany 1x, ostatnio: Silv, 2019-07-19 22:06

Pozostało 580 znaków

2019-07-19 22:07
0

Nie mówię, że jest to istotne dla twojego dewelopmentu, mówię, że to dobry dodatek dla osób, które chcą bez ryzyka pobawić się twoim programem, bez analizowania kodu źródłowego.

Co do kompatybilności i ogólnie basha - czemu nie wybrałeś cli w JSie? I tak apka Node'a wymaga ;)

Pozostało 580 znaków

2019-07-19 22:12
0
Maciej Cąderek napisał(a):

Co do kompatybilności i ogólnie basha - czemu nie wybrałeś cli w JSie? I tak apka Node'a wymaga ;)

To jest dobre pytanie. Najbliższe prawdy będzie chyba, że chciałem pokazać, że umiem napisać coś w Bashu. A Bash wydaje mi się (wciąż) najbardziej oczywistym wyborem, jeśli chodzi o CLI. A CLI wybrałem dlatego, żeby było szybko. Np. GUI webowe jednak tworzy mi się wolniej, nie mówiąc już o GUI na desktopy. Jeszcze mógłbym zrobić samo API, ale mnie chodziło o to, by nie była to biblioteka, tylko coś, czego można od razu użyć.


PS. Użyć i zobaczyć efekty.


PS2. W zasadzie chodziło mi o to, żeby nie trzeba było innej aplikacji, zewnętrznej. Ech, nie mogę się wysłowić. :D


edytowany 4x, ostatnio: Silv, 2019-07-19 22:18

Pozostało 580 znaków

2019-07-19 22:20
0

A Bash wydaje mi się (wciąż) najbardziej oczywistym wyborem, jeśli chodzi o CLI.

Nie, jeśli chcesz żeby można to było odpalić multiplatformowo bez dodatkowego zachodu, np w Powershellu/cmd ;)

edytowany 3x, ostatnio: Maciej Cąderek, 2019-07-19 22:26
O, właśnie! Ale to będę już robić później. Mam nadzieję, że nie będę musiał uczyć się PowerShella zbyt wiele. Liczy się jedynie fakt działania i możliwość oceny przeze mnie, czy działa poprawnie. - Silv 2019-07-19 22:27

Pozostało 580 znaków

2019-07-20 08:25
1

Do sprawdzania skryptu w bashu, polecam używać shellcheck, jest dostępny w repo popularnych dystrybucji.

Pozostało 580 znaków

2019-07-20 14:05
0

@TurkucPodjadek: dzięki, zobaczę, co to. Na razie koncentruję się na JS.


Pozostało 580 znaków

2019-07-28 02:15
0

Kolejne, duże, wydanie mojej aplikacji: 1.2.0 (link). Dodałem testy jednostkowe; wykorzystuję przy nich frameworki Mocha oraz Jest.

Jeżeli ktoś będzie chcieć, może je sprawdzić. Byłoby mi było miło. :)


UPDATE: Z innych zmian – nareszcie włączyłem wsparcie dla usługi Travis CI. Teraz mam fajny obrazek w README z tekstem build passing. :)


PS. Powiem wam, że zmęczyło mnie to. Potrzebuję chwili odpoczynku. A potem... z powrotem do pracy!


UPDATE2: Testy jednostkowe są dla kodu JavaScript. Jeśli chodzi o kod w Bashu – nie chciałem już tracić czasu na kombinowanie. Planuję dodać coś później w tym temacie.


UPDATE3:

Miałbym jeszcze pytanie: jak często powinienem wypuszczać nowe wydania? Chodzi mi o to, że obecnie nie mam ustalonego harmonogramu; robię tak: znalazłem 1 bug (lub kilka, ale musi być naraz) -> naprawiam go -> nowe wydanie; wymyśliłem nową funkcjonalność lub chcę usunąć istniejącą -> implementuję to -> nowe wydanie.

Narzut czasowy dla mnie nie wydaje się być zbyt duży, a cały proces jest spójny = łatwo mi nad nim panować. Ale z punktu widzenia użytkownika lub innego dewelopera – na podstronie z wydaniami na GitHubie robi się tłok. I jakoś to tak nie wygląda mi profesjonalnie.


edytowany 17x, ostatnio: Silv, 2019-07-28 02:51

Pozostało 580 znaków

2019-08-04 01:12
0

Kolejne, duże, wydanie mojej aplikacji: 1.3.0 (link).

Z większych zmian:

  • dodałem testy integracyjne (pisane we frameworku Jest);
  • nadałem status "deprecated" funkcjonalności testowania dostępnej przez public API.

Jeżeli ktoś będzie chcieć, może sprawdzić te testy. Byłoby mi było miło. :)

O, i przypomniało mi się – muszę jeszcze w dokumentacji dodać ten status. Ech.


edytowany 11x, ostatnio: Silv, 2019-08-04 01:15

Pozostało 580 znaków

Odpowiedz
Liczba odpowiedzi na stronę

1 użytkowników online, w tym zalogowanych: 0, gości: 1, botów: 0