Nazewnictwo dla nowego API powinno być ustalone od dawna, ale jako że nie było, teraz jest już na prawdę najwyższa pora.

Generalnie całe API przejmie nazewnictwo z szykowanej Stamina.Lib (zmienne z małej, nazwy klas, przestrzeni nazw - z dużej, zmienne prywatne z _ na początku, nazwyPisaneZUżyciemDużychLiterDoOddzielaniaWyrazów)

Do ustalenia jest tylko nazewnictwo identyfikatorów pól w tablicach, identyfikatorów komunikatów i klas do przenoszenia tych komunikatów...

Aktualnie jest:
Kolumny tablicy: CFG_NAZWA, CNT_NAZWA, CFG_KSOUND_MUTE
Komunikaty: IMC_FINDCONTACT, IMI_REFRESHLST, IM_STATUSCHANGED, IM_KSOUND_REGISTERSOUND
Struktury komunikatów: sIMessage_2params, sIMesage_statusChanged, sIMessage_kSoundRegisterSound
Akcje: IMIA_OPENMESSAGE, IMIG_MAIN, IMIA_KSOUND_MUTE

- Identyfikatory są często mało czytelne i bardzo długie,
- brakuje porządnego grupowania,
- nazwy struktur komunikatów są za długie
+ w stylu WinApi,
+ jest z nami od dawna
+ użycie pola tablicy lub komunikaty widać w kodzie od razu

Ostatnio używane:

Wszystko siedzi w swoich przestrzeniach nazw:
Kolumny: CFG::nazwa, CNT::nazwa, KSound::CFG::mute
Komunikaty: IM::findContact, IM::refreshList, IM::statusChanged, KSound::IM::registerSound
Struktury: IM::_2params , IM::_statusChanged, KSound::IM::_registerSound
Akcje: Act::openMessage, Act::gMain, KSound::Act::mute

- Duża liczba namespace'ów, zwłaszcza przy krótkich API wygląda często dziwnie i wydaje się przesadzona...
- IM::findContact, IM::refreshList są w jednej przestrzeni - brakuje rozróżnienia pomiędzy komunikatem do core/UI/wtyczki
- '_' w nazwie struktury jest sprzeczne z zasadami nazw stamina.lib i do tego zupełnie nie intuicyjne
+ mamy pełną dowolność w używaniu nazw przestrzeni... Można użyć IM::registerSound, jak i KSound::IM::registerSound...
+ kontekstowe podpowiedzi, np. w VisualStudio pokazują tylko identyfikatory z namespace'a więc znajdywanie prawidłowych jest banalnie proste

Propozycja 1:
Kolumny: CFG::nazwa, CNT::nazwa, KSound::CFG::mute
Komunikaty: IMC::findContact, IMI::refreshList, IM::statusChanged, KSound::IM::registerSound
Struktury: IM::TwoParams , IM::StatusChanged, IMC::FindContact, KSound::IM::RegisterSound
Akcje: ACT::openMessage, ACT::groupMain, KSound::ACT::mute

- jeszcze większa liczba przestrzeni nazw (IM, IMC, IMI)
- użyte w kodzie mają niższą "widoczność" od standardowcyh, chociaż w pewnym stopniu ratują je przedrostki przestrzeni nazw...
- identyfikator komunikatu od klasy rozróżnia tylko wielkość pierwszej litery
+ bardzo czytelny i jednoznaczny podział na przestrzenie
+ pełna zgodność z zasadami dla Stamina.Lib
+ wyjątkowo zgodne z podpowiedziamy kontekstowymi
+ bardzo łatwe w dokumentacji, doxygen elegancko rozbije przestrzenie

Propozycja 2:
Wszystko znajduje się w jednej przestrzeni - np. Konnekt, lub przestrzeni wtyczki np. KSound

Kolumny: CFG_nazwa, CNT_nazwa, KSound::CFG_mute
Komunikaty: IMC_findContact, IMI_refreshList, IM_statusChanged, KSound::IM_registerSound
Struktury: IMTwoParams , IMStatusChanged, IMCFindContact, KSound::IMRegisterSound
Lub ewentualnie: TwoParamsIM, StatusChangedIM, FindContactIM, KSound::RegisterSoundIM
Akcje: ACT_openMessage, ACT_groupMain, KSound::ACT_mute

- brak grupowania
- brak możliwości ominięcia przedrostka
- niezbyt zgodne z zasadami dla Stamina.Lib
+ jest prostą mieszanką tego co było, z tym co będzie :]


Dla zachowania zgodności stare define'y będą oczywiście nadal dostępne. Nowe deklaracje będą zmiennymi typu const o ściśle określonych typach (dzięki czemu będzie trudniej popełnić błąd podczas pisania kodu).

Wszystkie pozostałe obiekty będą używały zasad dla Stamina.Lib.

Gdy cała lista zasad zostanie porządnie skompletowana podamy ją do publicznej wiadomości

Czekam na komentarze...

IMHO propozycja numer 2 jest kiepska, brak podpowiedzi kontekstowych eliminuje prawie calkowicie rozwiazanie z define lub const z przedrostkiem. Skoro trzonem K ma być Stamina.Lib, która już jest w całości na przestrzeniach nazw, to API też powinno wykorzystywać do bólu przestrzenie.

Co do propozycji numer 1 to raczej problem jest poważny. W samych wtyczkach można zrobić poprostu kolejną przestrzeń (ja tak przynajmniej robie) np.: ggimage::act::send albo ggimage::cfg::maxfile, zastosowanie takie pozwala na łatwiejsze rozdzielanie

A nie możnaby zrobić np IM::UI::refreshList, a do struktur np IM::struct::*** (bądź do akcji IM::act::***). Pozostałaby wtedy tylko jedna globalna przestrzeń nazw, ale jednoczesnie byłoby to dość intuicyjne i pozostałoby czytelne.

PS. MiLKA czy nie chodziło Ci, że w przestrzeni nazw można utworzyć kolejną przestrzeń?

Aule, w ou propozycjach zakładam że wszystko siedzi w przestrzeni Konnekt, więc globalna przestrzeń jest tylko jedna...

Konnekt::IM::* Konnekt::CFG::* i w 2ej propozycji Konnekt::IM_*

Na pewno robienie osobnej przestrzeni nazw na struktury w IM nie ma większego sensu, zwłaszcza jeżeli z jakiegoś powodu powstaną kiedyś kolejne podprzestrzenie (kótre znowu będą musiały zawierać kolejny struct)...

Ogólnie problem z rozróżnianiem tylko po wielkości liter dlatego jest na niebiesko, bo dodałem go później, ale sam nie uważam tego za wielką przeszkodę...

Zastanawiałem się nad IM::UI::*, IM::Core::*, ale chyba robi się to przydługie w pisaniu i może niekoniecznie zwiększać czytelność...

Trzebaby to sprawdzić, ale jeżeli dobrze pamiętami aliasy namespace'ów można zrobić tak:


Więc wtedy można się dostać na oba sposoby: IM::UI::refreshList i IMI::refreshList

Ja myślałem, że to jest na niebesko, bo to ważne jest. Dla mnie to też szczególnie przeszkadzać nie będzie. Możnaby też 's' w nazwie dodawać dla struktur.

Ja też jestem za tym s na początku, ale hao uważa to za mieszaninę z innymi typami...

A oddzielnej przestrzeni dać nie chce Jeżeli to 's' nie może być to propozycja 1 jest lepsza.

nie mam wiele czasu na pzrzemyslenia wiec wybaczcie jesli cos pokrece.
Nie lepiej bylo by polaczyc przeezstrzeni nazw z wyliczeniami? Opre sie na .net. Nie jestem rozeznany w grupach identyfikatorow jakie sa uzywane w K ale moglo by to wygladac tak


I wtedy jesli ktos by potrzebowal identyfikatorow rdzenia by importowal przestrzen nazw "glowne", jesli jakiejs wtyczki no to "wtyczk1". A potem by uizywal w kodzie:

Komunikaty będą obiektami typu Object (Stamina.Lib)...
Nazewnictwo takich obiektów jest takie że:
Object - główna klasa obiektu (implementacja)
iObject - interfejs obiektu
oObject - współdzielony wskaźnik do obiektu

Jak widać s na początku wprowadzałoby zbędne zamieszanie...

Wracając do przestrzeni nazw, w nowym API jakiś czas temu napisałem obsługę Unique (rejestracja identyfikatorów) i Table (tablice danych). Komunikaty do tych modułów siedzą w przestrzeni nazwy modułu czyli
Konnekt::Tables::IM::* oraz Konnekt::Unique::IM::* co w zasadzie jest całkiem przejrzyste i zrozumiałe...
Teraz w Tables są komunikaty do rdzenia (np. registerTable) jak i komunikaty do wtyczek (np. rowAdded). Jeżeli przyjąć propozycję pierwszą trzeba by:
a ) wydzielić registerTable do Konnekt::Tables::IMC::registerTable...
b ) ustalić że przy tak małej liczbie komunikatów do rdzenia rozróżnianie jest zbędne i wrzucać wszystko do IM
c ) jak w b ale wszystkim komunikatom do wtyczek dodać przedrostek "event" dla lepszego rozróżnienia

Kosiarz: w C++ zawartość wyliczeń staje się globalna i nie da się do nich dostać przez nazwa::wyliczenie. Poza tym enuma nie można rozbić na kilka plików .H