Różnice między wybraną wersją a wersją aktualną.
|
pl:dydaktyka:jimp2:2016:part2:org:codepolicy [2016/04/20 22:37] msl utworzono |
pl:dydaktyka:jimp2:2016:part2:org:codepolicy [2019/06/27 15:50] |
||
|---|---|---|---|
| Linia 1: | Linia 1: | ||
| - | ====== Pisanie programów ====== | ||
| - | Oto kilka rad i wskazówek dotyczących pisania i komentowania kodu: | ||
| - | * [[#Komentowanie_kodu|Komentowanie kodu]] | ||
| - | * [[#Obsluga_wyjatkow|Obsługa wyjątków]] | ||
| - | |||
| - | ====== Komentowanie kodu ====== | ||
| - | * Wszystkie **deklaracje** funckji, **deklaracje oraz definicje** klas, w przypadku wielomodułowych programów staramy się umieszczać **w pliku nagłówkowym**. Staramy się unikać używania dyrektywy **#include** w plikach nagłówkowych, chyba że jest to niezbędne lub zamierzone. | ||
| - | * Pliki nagłówkowe powinny zawierać tylko niezbędne deklaracje oraz definicje. | ||
| - | * Pliki nagłówkowe powinny być **zabezpieczone** przed wielokrotną kompilacją: | ||
| - | |||
| - | <code cpp> | ||
| - | #ifndef PLIKH | ||
| - | #define PLIKH | ||
| - | |||
| - | // treść pliku nagłówkowego | ||
| - | |||
| - | #endif | ||
| - | </code> | ||
| - | |||
| - | * Dyrektywą **#include** włączamy tylko pliki nagłówkowe. **Niewolno** włączać plików *.c, *.cpp. | ||
| - | * Dla zwiększenia przejrzystości, szczególnie dużych plików (ponad 300 linii kodu) warto stosować dodatkowe separatory pomiędzy częściami kodu np. pomiędzy funkcjami: | ||
| - | |||
| - | <code cpp> | ||
| - | /// \brief opis funckji func1 | ||
| - | /// | ||
| - | /// \param __i - opis parametru __i | ||
| - | /// \param __f - opis parametru __f | ||
| - | /// \return funkcja zwraca: | ||
| - | /// \li 0 - w przypadku gdy... | ||
| - | /// \li 1 - w przypadku gdy... | ||
| - | /// \li 2 - w przypadku gdy... | ||
| - | int func1(int __i, float __f) | ||
| - | { | ||
| - | // Ciało funckji | ||
| - | } | ||
| - | // ---------------------------------------------------- | ||
| - | |||
| - | /// \brief opis funckji func2 | ||
| - | /// | ||
| - | /// \return brak zwracanych wartosci | ||
| - | void func2(void) | ||
| - | { | ||
| - | // Ciało funckji | ||
| - | } | ||
| - | // ---------------------------------------------------- | ||
| - | |||
| - | |||
| - | /// \brief opis funckji func3 | ||
| - | /// | ||
| - | /// \param __f_ptr - opis parametru __f_ptr | ||
| - | /// \return znak ktory reprezentuje | ||
| - | char func3(char(* __f_ptr)(int, float*& __in_ptr_ref)) | ||
| - | { | ||
| - | // Ciało funckji | ||
| - | } | ||
| - | // ---------------------------------------------------- | ||
| - | </code> | ||
| - | |||
| - | * Należy stosować **jak najwięcej** komentarzy. Krytyczne miejsca programu **muszą** być komentowane. | ||
| - | * Dodatkowym atutem, wpływającym na jakość tworzonego kodu jest stosowanie komentarzy zgodnych ze specyfikacją wymaganą przez Doxygen. Oto przykład komentarzy dla pliku nagłówkowego: | ||
| - | |||
| - | <code cpp> | ||
| - | /** | ||
| - | * \file nazwapliku.h | ||
| - | * \author Imie i Nazwisko | ||
| - | * \date 1.10.2008 | ||
| - | * \version 1.0 | ||
| - | * \brief Krótki opis co plik zawiera | ||
| - | */ | ||
| - | // ------------------------------------------------------------------------- | ||
| - | |||
| - | #ifndef PLIKH | ||
| - | #define PLIKH | ||
| - | // ------------------------------------------------------------------------- | ||
| - | |||
| - | /** | ||
| - | * \class klasa | ||
| - | * \author autor | ||
| - | * \date 1.10.2008 | ||
| - | * \brief Krótki opis klasy | ||
| - | */ | ||
| - | class klasa | ||
| - | { | ||
| - | private: | ||
| - | |||
| - | int f1; ///< opis pola klasy | ||
| - | int f2; ///< opis pola klasy | ||
| - | float f1; ///< opis pola klasy | ||
| - | |||
| - | public: | ||
| - | |||
| - | /// \brief Konstruktor domyślny klasy | ||
| - | klasa(void); | ||
| - | |||
| - | /// \brief Konstruktor klasy | ||
| - | /// | ||
| - | /// \param f - opis parametru | ||
| - | klasa(int f); | ||
| - | |||
| - | /// \brief opis metody 1 | ||
| - | /// | ||
| - | /// \param _a - opis parametru | ||
| - | /// \param *c - opis parametru | ||
| - | /// \return opis zwracanej wartości | ||
| - | int metoda1(int _a, double* c); | ||
| - | }; | ||
| - | // ------------------------------------------------------------------------- | ||
| - | #endif | ||
| - | </code> | ||
| - | |||
| - | Komentarze zgodne z Doxygen stosujemy tylko **raz** np. tylko w pliku nagłówkowym. Można a nawet trzeba sporządzać także komentarze "robocze", które nie będą uwzględniane przez narzędzie, szczególnie w najważniejszych miejscach programu. | ||
| - | |||
| - | * Staramy się robić wcięcia, dla kolejnych poziomów zagnieżdżeń kodu. Standartowo 3-5 spacji. | ||
| - | * **Nie używamy znaku tablulacji**: | ||
| - | * ponieważ powoduje to problem w przejrzystości kodu otwartego w innych edytorach niż ten w którym był pisany; | ||
| - | * z powyższego powodu konfigurujemy edytor tak aby zamieniał znak tabulacji na spacje; | ||
| - | * jeżeli edytor nie posiada takiej opcji to najwyższy czas go zmienić; | ||
| - | |||
| - | ====== Obsługa wyjątków ====== | ||
| - | Podczas pisania programów w ramach zajęć należy stosować mechanizmy obsługi sytuacji wyjątkowych. Poniżej zaproponowany sposób pozwoli na stworzenie kodu który w tym kontekście będzie prawidłowo przechodził testy. | ||
| - | * Ściągnij plik {{:pl:dydaktyka:jimp2:cpp:org:aghexception.zip|}} który zawiera definicję klasy przeznaczonej do obsługi sytuacji wyjątkowych. | ||
| - | * Klasa ma już gotowe metody które są gotowe do użycia. | ||
| - | * Jeżeli chcesz możesz tworzyć swoje klasy do obsługi błędów jednak aby mogły one poprawnie przechodzić testy muszą one dziedziczyć podaną klasę **aghException** w sposób publiczny. | ||
| - | * Niezastosowanie tej klasy do obsługi błędów będzie skutkowało możliwymi błędami podczas testów które w takim wypadku nie będą mogły zostać usprawiedliwione. | ||
| - | |||
| - | ===== Jak używać ===== | ||
| - | Poniżej prosty przykład użycia klasy. \\ | ||
| - | Mamy prostą funkcję **getValue** która zwraca wartość znajdującą się w tablicy **_tab** na miejscu o indeksie przesłanym jako argument. | ||
| - | Jeżeli wartość indeksu jest nieprawidłowa (tzn. poza zakresem tablicy) to w takim wypadku najlepszym rozwiązaniem jest wyrzucenie wyjątku (**throw**). | ||
| - | <code cpp> | ||
| - | int& aghVector::getValue(int _index) const | ||
| - | { | ||
| - | if((_index < 0) || (_index >= size())) | ||
| - | throw aghException(0, "Index out of range", __FILE__, __LINE__); | ||
| - | return _tab[_index]; | ||
| - | } | ||
| - | </code> | ||
| - | W powyższym przykładzie wykorzystana jest klasa **aghException**. Aby obsłużyć tak wyrzucony wyjątek np. w funkcji **main** robimy tak: | ||
| - | <code cpp> | ||
| - | try | ||
| - | { | ||
| - | v->getValue(-1) = 6; | ||
| - | } | ||
| - | catch(aghException& e) | ||
| - | { | ||
| - | cout << e << endl; | ||
| - | } | ||
| - | catch(...) | ||
| - | { | ||
| - | cout << "\nUnrecognized error\n"; | ||
| - | } | ||
| - | </code> | ||
| - | W tym przypadku obsługa wyjątku zostanie przekierowana do bloku: | ||
| - | <code cpp> | ||
| - | catch(aghException& e) | ||
| - | </code> | ||
| - | i na ekranie pojawi się taki komunikat: | ||
| - | <code> | ||
| - | Error in aghVector.h file at 69 line. | ||
| - | Error code: 0 (Index out of range). | ||
| - | </code> | ||
| - | Natomiast wszystkie pozostałe błędy które nie są obsługiwane przez podaną klasę będą obsługiwane w bloku: | ||
| - | <code cpp> | ||
| - | catch(...) | ||
| - | </code> | ||
