Przemyślenia powstałe podczas tworzenia programów w Clarionie.

Pokazywanie postów oznaczonych etykietą Standardy. Pokaż wszystkie posty
Pokazywanie postów oznaczonych etykietą Standardy. Pokaż wszystkie posty

piątek, 5 grudnia 2008

Standardy programowania - Wstęp

Dawno dawno temu w odległej galaktyce ... (tak to jest jak sie ciemne moce wpisuje jako backdoory). Dość dawno temu starałem sie ze znajomymi na bazie innego opracowania zastosować pewne zasady tworzenia programów. Obecnie chciałbym te zasady z Wami przedyskutować zmodyfikować i wdrożyć. Zapraszam do lektury i dyskusji.
Clarion for Windows
Development Standards
Revision 1.1PL 15.08.2005

By
Jim Morgan and Fred Schmitthammer
Wersja w języku polskim tłumaczona i weryfikowana przez
Olę Jańczak, Jacka Kosińskiego, Sławka Łopuszańskiego.
link do oryginału: http://www.clarionmag.com/col/98-04-c4devstandards.html?pFriendly=true
W odniesieniu do oryginału większośc propozycji zostało zmienionych, uwzględniono pomysły tak wielu ludzi z listy news.clarion.pik-net.pl, że trudno mi przypomnieć sobie, kto co proponował. Jednak wśród współautorów wymienić należy Piotra Rudnickiego, Mirka Sitarza oraz Grzegorza Siwca. Jeśli ktoś uważa, że powinien być wymieniony też na tej liscie to proszę o kontakt (kashiash@aip.pl).



Wprowadzenie
W dokumencie tym zajmujemy się zagadnieniami projektowania i programowania przy użyciu pakietu Clarion 4.x, i nowsze (obecnie 6.2). Dokument niniejszy bazuje na Zaleceniach Dla Programistów Interfejsu Windows – pozycji wydanej przez Microsoft Press. Wszelkich informacji nie zawartych w niniejszym dokumencie należy szukać w powyższej pozycji.
Standardy są ważne z wielu powodów. Dzięki korzystaniu ze wspólnego interfejsu użytkownika (UI) aplikacje stają się łatwiejsze do opanowania przez tegoż użytkownika. Spójne i proste projekty ekranów czynią pracę z nimi łatwiejszą i mniej stresującą. Pozwala to użytkownikowi na osiągnięcie lepszych rezultatów w korzystaniu z danego programu. Standardy programistyczne pozwalają grupie programistów na łatwiejszą współpracę w zespole. Używanie spójnego stylu kodowania zmniejsza ogólne koszty późniejszej konserwacji systemu, a także czyni łatwiejszym dokończenie czyjegoś programu bądź współużywanie bibliotek, które zostały stworzone przez innych.
Niektórzy twierdzą, iż standardy ograniczają kreatywność programistów i wymagają czasu w celu ich poznania i nauczenia się. Programiści mają jednak wiele możliwości wykazania się kreatywnością w ramach, narzuconych przez standardy. Standardów trzeba się nauczyć, to fakt, jednak zastosowanie standardowego podejścia do rozwiązywania problemów na ogół wielokrotnie rekompensuje czas, poświęcony na naukę. Ogólne korzyści, którymi są wydajność zespołu, wydajność użytkownika końcowego oraz niższe koszty konserwacji czynią stosowanie standardów niezbędnym w przypadku każdego projektu na tyle dużego, że konieczne jest zarządzanie nim.
To nie jest zamknięty dokument. Cały czas uczymy się lepszych metod. Zmiany technologiczne zachodzą ciągle. Standardy przemysłowe dotyczące UI zmieniają się również. Dokument niniejszy musi podlegać zmianom, by nadążać za bieżącymi potrzebami. Każda z osób posługujących się standardami może stworzyć propozycje zmiany, przedstawiając poniższe informacje osobie odpowiedzialnej:
Numer zmienianego standardu (lub propozycja nowego numeru).
Treść standardu
Argumentacja przemawiająca za przyjęciem nowego standardu
Argumentacja przemawiająca za odrzuceniem bieżącego standardu
Proponowane zmiany standardów zostaną rozprowadzone pośród członków komisji zajmującej się standaryzacją. Jeśli zmiany zostaną zaaprobowane, nowa wersja dokumentu zostanie udostępniona do pobrania. Obecna wersja powstała na bazie wersji sprzed 2ch lat i nowych doświadczeń, i jest w ciagłej modyfikacji wynikającej z braku czasu, postaramy sie zeby byla jak najbradziej aktualna - w koncu tylko w takiej postaci nadaje sie do wykorzystania.

Standardy programowania - Atrybuty okna

Ustawienie atrybutu centrowania dla wszystkich okien
Domyślne położenie bywa niepożądane, zwłaszcza w przypadku dużych okien.

Ustawienie atrybutu Entry Paterns dla wszystkich okien.
Pozwala na natychmiastową reakcje użytkownika.

Wszystkie okna projektowane w oparciu o siatkę 3 (szer.) X 3 (wys.). Opcja przyciągania do siatki powinna być włączona. Użyj “Options/Grid Settings” aby zmienić parametry siatki w Window Formatter.
Przyspiesza to równe ułożenie elementów okna.

Wszystkie okna powinny używać standardowego kroju Arial CE 8pt. Nie należy stosować kolorów ani stylów, chyba że jest to niezbędne.
To jest domyślne ustawienie Clariona dla Windows. Okna powinny być proste, jednolite i łatwe do prześledzenia.

Każda kontrolka, do której użytkownik ma dostęp powinna mieć przyporządkowany unikatowy klawisz skrótu.
Użyj znaku ‘&’ do określenia klawisza skrótu dla dostępu bez użycia myszy.

Każda grupa kontrolek powinna być obwiedziona prostokątem (group box).
Grupuj skojarzone tematy ze sobą, gdy w ramach zakładki istnieje kilka grup.

Wszystkie opisy pól i wskazówki powinny być wyrównane do lewej strony.
Spójność.

Każdy ekran powinien mieć przypisany identyfikator pomocy (Help ID).
Używany do tworzenia haseł pomocy dla danego ekranu.

W tekstowych opisach pól czy elementach menu stosuj Wielkią literę na początku wyrażenia, pozostałe wyrazy z małej. Po każdym opisie umieszczaj dwukropek (np.’Kod pocztowy:’).
Kombinacja wielkich i małych liter jest łatwiejsza do przeczytania.

Typ obramowania: używaj generalnie ‘Single’, jednak dla okienek modalnych stosuj ‘Double’ a dla okienek przeglądania (Brwowsy) używaj ‘Resize’.
Pozwala to na optyczne rozróżnienie okienek różnych typów.

Maximize Box zaznaczamy tylko na oknach, których podstawowym elementem jest lista (browse), na pozostałych tj. formatkach itp. ta opcja powinna być wyłączona.


Zaznaczamy opcję System Menu

Standardy programowania - Atrybuty obiektów

Każdy przycisk paska narzędzi powinien mieć przyporządkowaną ikonę i ‘dymek’ podpowiedzi.
Spójność.

Każdy przycisk na formularzu powinien mieć ikonę oraz tekst.
Spójność.

Każde pole powinno mieć przypisany atrybut komunikatu.
Kreator tworzy ‘dymki’ automatycznie, jeśli opis pola jest w słowniku.

Każda zmienna przypisana do danego pola powinna mieć nazwę analogiczną do nazwy pola (np. ?pat:Fname)
Kod samodokumentujący się.

Nazwa każdej zmiennej przypisanej do opisu pola powinna składać się z nazwy pola, dwukropka i słowa PROMPT. (np. ?pat:Fname:Prompt)
Kod samodokumentujący się.

Nazwa każdej zmiennej przypisanej do opcji menu powinna składać się z przedrostka Mnu i nazwy wywoływanej procedury. (np. ?MnuBrwKlienci)
Kod samodokumentujący się.

Nazwa każdej zmiennej przypisanej do przycisku powinna składać się z przedrostka Btn i nazwy wywoływanej procedury (np. ?BtnBrwKlienci )
Kod samodokumentujący się.

Używaj checkboxów do opcji typu ‘Tak/Nie’. Do opisu używaj zdań twierdzących.
Spójność.

Używaj list rozwijanych typu combo-box zamiast przycisków opcji.
Spójność.
akurat ten punkt przydaloby sie przedyskutowac, co prawda chceboxy zajmuja wiecej miejsca ale program jest bardziej czytelny bo od razu widac co user ma wybrac - JK
Każdy przycisk ze skojarzonymi plikami potomnymi powinien zawierać szablon Child Files. (dostepny w klubowych szablonach)
Spójność.

Tekst etykiet (prompt) jest czarny, pisany z dużej litery i na takim samym tle jak okno.
Spójność.

Kolor czerwony (red) zarezerwowany jest dla celu podkreślenia w księgowości kwot (liczb) ujemnych.
Spójność.


Rozmiary

Wszystkie elementy okienka powinny używać ustawień danego okienka dla kroju, rozmiaru i stylu czcionki.
Spójność.

Wszystkie przyciski powinny mieć jednakowe rozmiary, domyślnie 48(szer.) X 16(wys.). Można użyć szerszych przycisków, gdy konieczne jest użycie dłuższego opisu.
Spójność.

Przyciski paska narzędzi powinny mieć jeden z dwóch rozmiarów: 24(s) X 22(w.) albo 32(s.) X 30(w.). Ikona przycisku powinna mieć rozmiary 16 X 16 lub 24 X 24.
Spójność.

Wszystkie pola tekstowe, spinboxy, i listy rozwijane powinny mieć ustawiony atrybut rozmiaru na ‘Default’. Ustawienie jest dostępne w sekcji ‘Position’ właściwości pola. Spowoduje to uzyskanie pól o wysokości 10 jednostek dla fontu 8-punktowego.
Spójność.

Wszystkie opisy pól powinny mieć ustawiony atrybut rozmiaru na ‘Default’. Ustawienie jest dostępne w sekcji ‘Position’ właściwości opisu. Spowoduje to uzyskanie opisów o wysokości 9 jednostek dla fontu 8-punktowego.
Spójność.
(te rozmiary na default warto sprawdzic, bo oryginalna dokumentacja byla pisana do MS San Serif, a teraz uzywamy Arial CE- JK
Przyciski VCR Buttons mają rozmiary 12 X 12.
Spójność.

Eliptyczne przyciski używane do wyszukiwania w bazie powinny mieć rozmiar 12W x 12H. Powinny mieć ikonę lookup’u i ‘dymek’ z opisem.
Spójność.


Rozmieszczenie

Wszystkie elementy okien dialogowych powinny być oddalone o 6 jednostek ( czyli dwa kroki siatki) od górnej bądź dolnej krawędzi okna. Wszystkie kontrolki powinny być również oddalone o 6 jednostek od spodu arkusza i od góry następnego pola. Pierwszy element na arkuszu powinien również być oddalony o 6 jedn. od spodu bądź góry arkusza.
Spójne, przejrzyste i wizualnie wyrównane okienka.

Wszystkie pola powinny być oddalone w pionie o 3 jedn. (1 krok siatki) i w poziomie o 6 jedn. (2 kroki siatki) od sąsiednich pól..
Spójne, przejrzyste i wizualnie wyrównane okienka.

Górna krawędź opisu pola powinna być umieszczona 3 jednostki (1 krok siatki) poniżej górnej krawędzi odpowiedniego pola. Opis powinien zawsze kończyć się dwukropkiem.
Spójne, przejrzyste i wizualnie wyrównane okienka.
To jest łatwe jak na promptach uzywa się rozmaru default, wtedy ich wysokośc jest mniejsza i ten punkt wtedy latwo wdrozyc – w wierszu rownac kontrolki i prompty w dół.
Wszystkie kontrolki powinny być wyrównane do lewej krawędzi okna. Przyciski stanowią wyjątek.
Spójne, przejrzyste i wizualnie wyrównane okienka.

Wszystkie kontrolki powinny być umieszczone w arkuszu właściwości formatera okienek, z wyjątkiem ogólnych przycisków, jak OK., Anuluj, Zamknij czy Pomoc, dotyczących całego okna.
Spójne, przejrzyste i wizualnie wyrównane okienka.

Nazwy ikon powinny być samoopisujące i spójne. (np., ok.ico dla ikony przycisku OK).
Spójność i łatwość zamiany ikon w całym systemie jednocześnie.
Nawet jeśli nie masz w danej chwiuli odpowiedniej ikony, wymysl dla niej nazwę taką wpisz w clarionie i skopiuj kontrolke cancel.ico pod tą nazwę. Wlasciwą ikonkę dobierzesz w przyszłości.
Wszystkie typowe przyciski powinny zawierać swoją własną ikonę. Ta opcja dostępna jest pod zakładką Extra na ekranie właściwości przycisku.
Spójność.

Wszystkie elementy okna powinny być umieszczone jeden pod drugim w pionie.
Spójność i łatwość odświeżania wyświetlanego ekranu.

Elementy powiązane ze sobą będą oddalone od siebie o 6 jednostki w poziomie i 3 jednostki w pionie (odp. 2 i 1 krok siatki). Elementy niepowiązane ze sobą będą oddalone od siebie o 9 jednostek w poziomie i 6 jedn. w pionie (odp. 3 i 2 kroki siatki).
Spójne, przejrzyste i wizualnie wyrównane okienka.

Jeśli na oknie występuje tylko jedna zakładka (General), to powinna być wyeliminowana. Jedynym wyjątkiem są okienka przeglądania danych, na których zakładka wskazuje sposób sortowania danych.
Spójne, przejrzyste i wizualnie wyrównane okienka. Uwaga: można to łatwo osiągnąć w kodzie źródłowym ekranu.

Przyciski powinny być umieszczone pod poziomo arkuszem, albo ułożone jeden nad drugim przy fragmentach, których dotyczą wykonywane przez nie akcje.
Spójne, przejrzyste i wizualnie wyrównane okienka

Przyciski poleceń odnoszące się bezpośrednio do wyświetlanych danych są zawsze umieszczane w dolnej części okna zaczynając od prawej strony przyciskiem 'Pomoc' lub w jego braku przyciskiem 'Zamknij'. Przyciski wywołujące tzw. potomków czyli okna zawierające dane podrzędne (podporządkowane) bieżącym umieszczane s± zawsze z lewej strony okna, zaczynając od góry.


Jeśli na danym ekranie znajdują się dwa lub więcej elementów typu lista (browse), to ich kolejność w zależności od hierarchii jest od góry do dołu i od lewej do prawej, a przyciski i opisy s± rozmieszczane wg wyżej wymienionych zasad w stosunku do właściwej dla nich listy (browse'a).

Standardy programowania - Wydruki

Nazwa procedury z wydrukiem to Rep.
Spójność

W menu głównym powinna być przewidziana opcja 'Wydruki', do której
powinny być 'podwieszane' wszystkie aktualne wydruki wywoływane z danego okna (nie mylić z zestawieniami - zestawienie zawsze generuje wydruk, nigdy nie zachodzi zdarzenie odwrotne).


Tytuł raportu wyrównany do lewej czcionka 14 punktów pogrubiona
Spójność

Na kazdym wydruku w stopce należy umieścić date i godzinę utworzenia raportu oraz numer kolejny strony. Najlepiej wykorzystać gotowe szablony dostarczane z Clarionem.
Spójność

Kolumny separować prostokatami a nie liniami, nie uzywać cieniowania w nagłówkach


Kazda strona powina mieć 1/2 calowy górny i boczny margines oraz 3/4 cala na dole strony.
Unikniemy obcinania stron na niektórych drukarkach

W opcjach konfiguracji wskazane jest umożliwienie przesunięcia wydruku względem strony przez uzytkownika końcowego


Na raportach uzywamy jednostek 1/1000 cala
Daje najwieksze pole manewru.

Standardy programowania - Struktury danych

Klucze mają przedrostek Key. (np KeyNazwaKontrahenta). Klucze unikalne mają przedrostek nie Key, ale UKey, np. UkeyPesel
Spójność

Wszystkie pliki powinny mieć nastepujace pola:
ID. DataModyfikacji, CzasModyfikacji, IDOperatora_fk
Normalizacja danych

Kazdy plik powinien miec nastepujace indeksy:
- KeyIDKey który ma ustawione opcje: Auto Incrementing, Unique, Primary Key. W kluczu tym umieszczamy pole ID
- KeyModified, bez żadnych. W kluczu tym umieszczamy pola: IDOperatora_fk, DateModified, TimeModified.
Normalizacja danych

Pliki będące w relacji powinny być powiązane za pomoca pól ID . Pola te powinny byc zadeklarowane w obu plikach, w pliku z kluczem obcym z końcówką ‘_fk’. Relacja powinna miec ustawiona kontrole integralności na cascade lub restrict.Pola ID nie mogą być modyfikowane przez uzytkownika. Klucze obce w nazwie mają końcówkę "_fk".
Integralność

Przy definiowaniu słowników należy zwrócić szczególną± uwagę na wykorzystanie przy definiowaniu pól opcji:
Derived From służącej do dziedziczenia definicji pola
Do Not Auto-Populate This Field dla pól (np. typu ID), które nie powinny się z automatu pojawiać na ekranach i raportach - musi to być świadoma decyzja.
Jednocześnie zwracam uwagę, aby nie odpuszczać sobie wypełniania pozycji Description, Prompt Text, Column Heading, Message
Przy korzystaniu z opcji Derived From należy zwrócić uwagę na to, by
dziedziczenie odnosiło się we wszystkich przypadkach w ramach jednego słownika do jednego macierzystego pola, ponieważ w przypadku zastosowania łańcucha dziedziczeń opcja Refresh Dictionary obsługuje tylko jeden poziom zagłębienia. W przypadku łańcucha należałoby j± uruchomić tyle razy ile ogniw liczy łańcuch.


We właściwościach bazy należy obowiązkowo wybrać opcję OEM oraz zalecane jest stosowanie opcji Open in Current Thread, która to opcja powoduje zarezerwowanie w każdym wątku bufora dla bazy czyli faktycznie umożliwia pracę wielowątkową na tej samej bazie.


Przy definiowaniu zmiennych i pól należy zwrócić uwagę na następujące atrybuty:
i. Initial value - można tu nawet wpisywać funkcje i dzięki właściwej definicji oszczędzić sobie pracy z inicjowaniem danych poprzez wstawki w kodzie źródłowym
ii. Values - można dzięki właściwej definicji oszczędzić sobie pracy przy późniejszej obróbce jako, że wartości są całkowicie niezależne od zawartości pola Choices


Typy danych
Typ Danych SQL Topspeed Driver
ID LONG. ULONG,
Czas
Przechowywane jako cstring(8). Maska @t3.
Przechowywany jako Long. Maska @t3 lub @t6 gdy należy pokazywać sekundy.
Daty
Przechowywany jako cstring(11)
Przechowywany jako Date. Maska d17.
Strings
Zawsze jako cstring.
Zawsze jako cstring.
Memo
Duże pole cstring
Duże pole cstring
Groups
Nie uzywane w plikach
Nie używane w plikach

Kwoty
Decimal, n@16_’2
Decimal, n@16_’2
TAK/NIE
Byte(0,1) lub
Byte(0,1)
Generalnie: Nie stosować liczbowego picture, w którym grupowanie tysięcy następuje
przecinkiem (chyba domyślny - używać spacji, np. nie n10.2 - ale n10_.2


Wydaje się słusznym opracowanie własnej puli typów i używanie ich podczas definiowania tablic w słowniku

Standardy programowania - Pisanie kodu

ZŁOŻONE PROCEDURY POWINNY BYĆ PISANE JEDNOKROTNIE. Jeśli musisz odwoływać sie wielokrotnie do skomplikowanych obliczeń etc., zrób z tego funkcję, routine, lub szablon. Za złożone wyrażenia przyjmij takie gdzie jest więcej niż 2 linijki tekstu lub ponad 100 znaków.
Utrzymanie i konserwacja

Unikaj pisania całego wyrażenia IF end w pojedynczej linii.
Łatwość śledzenia

Zmienne globalne z prefixem GLO, bez ":" na końcu !
Spójność

Zmienne lokalne bez prefiksu LOC
Spójność

Kod oprócz etykiet powinien rozpoczynać sie w 3 linii. Wcięcia dla wyrażeń kończonych komendą END, 2 spacje. (Accept, Loop, If, Case, Execute)
Spójność

Używaj END !Wyrażenie zamiast kropki na końcu. np.:
Accept
Loop While Something = True
Case ActionCode
OF AddRecord
Do AddRoutine
OF ChangeRecord
Do ChangeRoutine
Else
Do DefaultRoutine
End !Case ActionCode
If Expression = True
And SomethingElse > LowValue
Another Expression
End!If Expression = True ...
End !Loop While Something = True
End !Accept
Łatwość czytania i analizowania

Wyrażenia logiczne powyżej 5 poziomów zagnieżdżeń powinny być w osobnych routinach.
Łatwość czytania i analizowania

Zalecana maksymalna wielkośc routine to 40 linii
Łatwość czytania i analizowania

Wszystkie wyrażenia powinne być w trybie twierdzącym. Nie używać NOT.
Łatwość czytania i analizowania

Uzywaj <> jako “różne od”.
Spójność

Nie używaj średników, nie umieszczaj kilku instrukcji w jednej linii.
Łatwość czytania i analizowania

Unikaj pisania linii kodu powyżej 80 kolumny. Użyj aby kontynuować pisanie kodu w następnych liniach. Jeśli kontynuujesz wyrażenie w komendzie IF przesuń następna linię o 1 spację.
Łatwość czytania i analizowania

Umieść co najmniej po jednej spacji przed i po znaku = . Użyj więcej znaków aby wyrównać znaki = w większych fragmentach instrukcji przypisania.
Łatwość czytania i analizowania

Używaj Like kiedy definiujesz zmienne ze sobą powiązane.
Utrzymanie

Często używaj pustych linii w celu odseparowania różnych fragmentów kodu .
Łatwość czytania i analizowania

Umieszczaj skomentowane linie (!-----) o długości 80 znaków na początku i końcu każdej podprocedury (routine), procedury, oraz w celu oddzielenia powiązanych fragmentów danych.
Łatwość czytania i analizowania

Kod powinien być czytelny i samodokumentujący. Komentarz powinien być umieszczony w tej samej linii dla każdego nietrywialnego wyrażenia. Każda procedura powinna być opisana z podaniem nazwy autora, daty utworzenia i modyfikacji. Informacja te powinna być uaktualniane przy każdej modyfikacji tej procedury.
Łatwość czytania i analizowania, utrzymanie

Należy używać kodu OOP, zgodnego ze standardem ABC Templates.
Utrzymanie

Umieszczaj jedną podprocedurę (routine) we wstawce (embed). Pierwsza linia powinna zawierać nazwe podprocedury i krótki jej opis. W dalszych liniach powinien być dokładny opis tego co podprocedura wykonuje.
Łatwość czytania i analizowania

Po operacjach I/O należy sprawdzać errorcode().
Unikanie błędów.



Nazewnictwo
Standard
Komentarz

Nazwy zmiennych powinny być oczywiste (należy unikać skrótów) skróty są akceptowalne przy nazwach dłuższych niż 20 znaków.
Self-documenting code.

Wszystkie pliki powinny mieć nazwy 16 bitowe (8+3 znaków). Wewnątrz programu nie używamy nazw długich, jednak program musi umożliwiać wprowadzanie i przechowywanie długich nazw plików.

Kompatybilność wstecz.


Nazewnictwo procedur
Browse
Brw
Form
Frm
Frame
Main
Process
Pro
Report
Rep
Source
Src
Splash
Spl
Viewer
Vie
Window
Win


Spójność

Nazwy procedur w menu (tzw. MenuText) jeśli aplikacja ma polski interfejs, jest polskojęzyczna to nie można stosować nazewnictwa nazw własnych oraz form rozkazujących zamiast imiesłowowych, np. "Wpisz AkcjeReklamowezZamówieńDoFaktur", powinno być "WpisanieAkcjiReklamowychZZamówienDoFaktur".






Standard
Komentarz




Nazwy zmiennych powinny być oczywiste (należy unikać skrótów) skróty są akceptowalne przy nazwach dłuższych niż 20 znaków.
Self-documenting code.

W modułach aplikacji kompilowanych jako *.dll wszystkie procedury są podłączone do lokalnego Menu (procedura typu Frame); nazwa procedury Menu pochodzi od nazwy aplikacji (modułu app, np. MenuDokumenty, MenuRaporty,MenuAdmin).

Współtwórcy