Tekst źródłowy strony Algorytmy/Dla twórców podręcznika


__NOTOC__
== Dla twórców podręcznika ==
Niniejsza strona zbiera zalecenia dla autorów i standardy, w jakich pisany będzie podręcznik. Aktualnie znajduje się on w BARDZO początkowej fazie tworzenia, dlatego możliwe są zmiany. Wszelkie nowe propozycje prosimy zgłaszać na stronie [[Dyskusja:Algorytmy/Dla twórców podręcznika|dyskusji]].

=== Styl ===
Podręcznik adresowany jest przede wszystkim do osób rozpoczynających swą przygodę z algorytmami, a także pragnących uporządkować swą wiedzę na ten temat. Staramy się pisać tak, aby nie przypominał on pracy zaliczeniowej jakiegoś znużonego studenta - najważniejsza jest przystępność oraz staranność opisów. Nie mamy nic przeciwko opisom obrazowym, ponieważ jest to świetne uzupełnienie naukowych i technicznych definicji.


Podręcznik dodatkowo zawiera dwa rozdziały zatytułowane odpowiednio: [[Algorytmy/Implementacje w C++|Implementacje w C++]] oraz [[Algorytmy/Implementacje w Pascalu|Implementacje w Pascalu]] pokazujące działające przykładowe  implementacje ( [[Kody źródłowe|kody żródłowe]] ) w dwóch językach programowania [[C++]] oraz [[Pascal]] wraz z przykładami użycia. Mają one charakter zapoznawczy.

Podręcznik zakłada, że czytelnik ma jakieś pojęcie nt tego, czym jest '''złożoność obliczeniowa''' oraz co to są struktury danych. W razie czego, jest ona dokładniej wyjaśniona we [[Struktury danych |wcześniejszej książce]], zatem można śmiało stosować w opisach notację dużego <math>O</math> oraz dużej <math>\Omega</math>.

=== Przykłady ===
We właściwej części podręcznika do prezentacji algorytmów stosujemy pseudokod ze składnią Pascalową. Uproszczenia polegają na tym, że niektóre fragmenty zastępujemy krótkim opisem słownym - przeważnie dotyczy to miejsc, gdzie implementacja tego, co napisaliśmy, okropnie zagmatwałaby kod. Ponadto korzystamy z operacji zdefiniowanych na początku rozdziału (np. ''INSERT'') jak funkcji, również, aby uprościć kod. Przyjmujemy, że nazwy operacji zapisane są dużymi literami. Opis słowny umieszczamy między znakami mniejszości i większości. Oto przykład:
 <pre class="lang-pas">procedure ABC(V: Data);
var S: Set;
    P: Data;

begin
   for <każdy element P w zbiorze S> do
   begin
      write(P);
   end;
end;</pre>

Stosujemy nazewnictwo:
# Angielskie nazwy struktur danych jako typy, np. ''Set'', ''List''
# Typ ''Data'' do reprezentowania jakichś abstrakcyjnych danych umieszczanych w strukturze, z której korzysta algorytm.
# Reszta małymi literami.

Przyjmujemy, że funkcja ''write'' potrafi wyświetlić wszystko.

Jeśli chodzi o dział ''Implementacje'', stosujemy następujące reguły:

==== C++ ====
# [http://www.stroustrup.com/Programming/PPP-style.pdf Styl] docelowy.
# Wcięcia czteroznakowe (spacja).
# W nazewnictwie posługujemy się underscore (tj. zmienne, funkcje itd. nazywamy jako ''nazwa_funkcji'', a nie ''nazwaFunkcji'' albo ''nazwafunkcji'').
# Poszczególne części algorytmu staramy się separować linijką przerwy.
# Kod musi być skomentowany, najlepiej komentarzami jednolinijkowymi.
# Implementacja musi być zapisana z użyciem programowania strukturalnego wraz z abstrakcją danych.
# Kod piszemy w języku angielskim.
# Komentarze piszemy w języku polskim.
# W implementacji '''NIE''' korzystamy ze struktur danych dostępnych w STL - w końcu po to jest ten dział, by czytelnik sam nauczył się dane struktury pisać.
# Używamy C++11 oraz C++14.

==== Pascal ====
# Wcięcia trójznakowe
# "begin" w nowej linijce
# W nazewnictwie posługujemy się camelStyle (tj. zmienne, funkcje itd. nazywamy jako ''nazwaFunkcji'', a nie ''nazwa_funkcji'' albo ''nazwafunkcji'').
# Poszczególne części algorytmu staramy się separować linijką przerwy.

=== Formatowanie ===
W opisie stosujemy następującą konwencję:
# ''kursywa'' - nazwy zmiennych, funkcji przy nawiązaniach do kodu algorytmu
# '''pogrubienie''' - nazwy struktur kontrolnych, np. '''for''', '''if''' oraz predefiniowanych wartości, np. '''null'''
# Akapitów używamy zgodnie z przeznaczeniem, tj. do zmiany wątku, a nie do separacji zdań, jak czasem się niektórym zdarza robić.
# Kolorujemy składnię! Szczegóły: [[Pomoc:Podświetlanie_składni]]

=== Szablony ===
Oto wykaz szablonów używanych w podręczniku:

{| border="1" cellpadding=3 cellspacing=0 style="margin: 0; border: 1px #aaaaaa solid; border-collapse: collapse; width: 100%; background-color: #ffffff"
|- style="background-color: #efefef; font-size: 95%"
! width="25%" | Opis !! Kod  !! Efekt
|-
| Ostrzeżenie czytelnika
| {{S|Uwaga|Tekst ostrzeżenia}}
|
{{Uwaga|Tekst ostrzeżenia}}
|-
| Porada
| {{S|Porada|Tekst porady}}
|
{{Porada|Tekst porady}}
|-
| Informacja
| {{S|Infobox|Tekst informacji}}
|
{{Infobox|Tekst informacji}}
|-
| Definicja
| {{S|Definicja|Tekst definicji}}
| {{Definicja|Tekst definicji}}
|-
| Do zrobienia
| {{S|TODO|co zrobić}}
| {{TODO|co zrobić}}
|-
| Do zrobienia
* do wstawiania w sekcji
* stosować tylko w rozdziałach, w których większość tekstu jest napisana
| {{S|RDoZrobienia}}
| {{RDoZrobienia}}
|-
| Artykuł do poprawy
| {{S|Dopracować|powód}}
| {{Dopracować|powód|bez kategorii=tak}}
|}

=== Nawigacja ===
Do nawigacji używamy standardowych szablonów w wersji podstawowej: <nowiki>{{</nowiki>Nawigacja|Algorytmy|poprzednia_strona|nastepna_strona<nowiki>}}</nowiki> Co daje w wyniku coś podobnego do :


{|border="solid" color="black"
 |{{Nawigacja|Algorytmy|poprzednia|nastepna}}
|}


Więcej informacji na stronie szablonów : [[Wikibooks:Szablony/Nawigacja]]