Eclips + Javadoc

Eclipse ułatwia korzystanie z javadoc-u. Aby wygenerować szkielet komentarza, należy:

• Wpisać ciąg znaków: „*/**”,
• Umieścić kursor w linijce z nagłówkiem klasy/ metody/ zmiennej, którą chcemy skomentować. Z menu kontekstowego wybrać Source->Add javadoc comment, lub nacisnąć Shift+Alt+J.

Np. dla metod zostanie wygenerowany komentarz zawierający odpowiednie wpisy:

•  @param,
•  @returns,
•  @throws.

Szkielet komentarzu można modyfikować w preferencjach Eclipse'a: menu Window->Preferences->Java->Code Style->Code Templates.

Aby wygenerować dokumentacje należy wybrać: menu Project -> Generate Javadoc. Można tam określić dla jakich pakietów, czy klas chcemy wygenerować dokumentacje, albo jakie tagi uwzględnić.

Dobre praktyki kodowania

Dobry kod jest:

• czytelny,
• prosty,
• wydajny,
• minimalny,
• łatwy do zmiany,
• posiada testy,

Pisanie kodu:

Najważniejsza jest czytelność kodu. Pisany kod powinien być zrozumiały dla innych, nie tylko do piszącego.

Nie powtarzaj się, bez sensu jest pisać kod wykonujący tą samą funkcjonalność w kilku miejscach.

Pliki nie powinny być większe niż 500 wierszy, a wiersz nie powinien być dłuższy niż 120 znaków. Zapewni to większą czytelność kodu, bez potrzeby długiego przewijania pliku.

Używaj wcięć w kodzie: przy warunkach, zagnieżdżeniach czy pętlach.

Nazwy:

Nazwy metod powinny być czasownikami,

Nazwy zmiennych, klas i obiektów powinny być rzeczownikami,

Nazwy klas – zaczynane od dużej litery (np. Student),

Stałe  - złożone tylko z dużych liter (np. MAX_VALUE),

Metody i zmienne zaczynają się małą literą, a nowe słowo z dużej bez podkreślników, myślników, innych odstępów w nazwie (np. returnOsoba),

Nazwy powinny mieć znaczenie,

Nazwy mogą być długie, nie używać niezrozumiałych skrótów,

Nazwy nie powinny być podobne do siebie,

Nazwy powinny odnosić się do rozwiązywanego problemu,

Nazwy powinny być możliwe do wymówienia,

Nie używać jednoliterowych zmiennych chyba ze jako licznik pętli (i,j,k)

Unikać słów kluczowych np. manager, procesor, info,

Używać set, get, is.

Metody:

Metody powinny być krótkie (max 20 wierszy),

Jak najmniej kodu w pętlach i warunkach (najlepiej jeden wiersz),

Metody nie powinny mieć wielu argumentów (najlepiej 0, max 3),

Metoda powinna wykonywać tylko jedno zadanie i nie mieć efektów ubocznych,

Metoda nie powinna robić czegoś co nie wynika jasno z jej nazwy,

Metody muszą być zrozumiałe,

Długą obsługę wyjątku lepiej przenieść do nowej metody,

Metody w klasie powinny być ułożone hierarchicznie. Bezpośrednio pod metodą wszystkie metody w niej wykorzystywane,

Metoda powinna korzystać tylko z metod udostępnionych przez:

• macierzysty obiekt,
• obiekty podane w argumentach,
• obiekty które sama stworzyła,

Komentarze:

Najlepszą formą komentarza jest sam kod. Lepiej gdy komentarzy jest jak najmniej, a jeżeli już wystąpił powinien być zwięzły. Komentarze mają tendencję do utraty aktualności, w miarę starzenia się kodu. Lepiej zmienić kod, tak aby był czytelniejszy niż komentować kod nieczytelny. Nie używać graficznych podziałów kodu np. /////////////////// filtr /////////

Nie zakomentowywać kodu – później nie wiadomo co on robił do czego służył i czy można go usunąć.

Zły komentarz to komentarz:

• opisujący oczywistość,
• nieaktualny,
• kłamliwy,
• który nic nie wnosi,

Gdzie można komentować:

• copyright u góry pliku,
• cel wykonania wydawałoby się bezsensownych akcji,
• wytłumaczenie użytych bibliotek,
• komentarze TODO – rzeczy do zrobienia w przyszłości (najlepiej żeby było ich jak najmniej i żeby szybko go usunąć).

Podstawowe operacje. Cz. 1. „Zmienne i pętle”

Zmienne

Zanim przejdziemy do omówienia podstawowych operacji musimy omówić zmienne. Zmienne są to liczby, znaki, napisy itd., które się zmieniają w trakcie wykonywania programu. Proste. Aby zadeklarować, czyli utworzyć taką zmienną musimy podać jej typ (czyli właśnie czy to będzie liczba, czy np. napis) oraz jej nazwę, którą będziemy się posługiwać.

  int calkowita; // liczba całkowita bez podanej wartości
  calkowita = 8; // deklaracja naszej liczby
  char znak = 'p'; // znak
  String napis = "xxxxx"; // napis

                 

Powyżej widać przykładową deklaracje trzech zmiennych. Aby wypisać taką zmienną na konsoli posłużymy się znaną już komendą:

                        System.out.println("liczba: " + calkowita + " a teraz string: " + napis);

Zmienna pomiędzy  plusami zostanie wstawiona w tekst. Klasa po zmianach wygląda teraz tak:

public class PierwszaKlasa {
  public static void main(String[] args) {
    int calkowita; // liczba całkowita bez podanej wartości
    calkowita = 8; // deklaracja naszej liczby
    char znak = 'p'; // znak
    String napis = "xxxxx"; // napis
    System.out.println("liczba: " + calkowita + " a teraz string: " + napis);
  }
}

A wynikiem jest:

liczba: 8 a teraz string: xxxxx

Pętla „while”

Pętla „while” czyli „dopóki” będzie się wykonywała dopóki warunek w niej zawarty jest prawdziwy. Ogólnie wygląda to tak:

while(warunek){

ciało pętli

}

Podam prosty przykład:

while(calkowita > 0){
   System.out.println("while: " + calkowita + " a teraz string: " + napis);
   calkowita = calkowita - 1;
}

Zwróci wynik:

while: 8 a teraz string: xxxxx

while: 7 a teraz string: xxxxx

while: 6 a teraz string: xxxxx

while: 5 a teraz string: xxxxx

while: 4 a teraz string: xxxxx

while: 3 a teraz string: xxxxx

while: 2 a teraz string: xxxxx

while: 1 a teraz string: xxxxx

Pętla „for”

Pętla, która będzie się wykonywała dla (for) jakiegoś warunku. Pętla jest bardzo podobna do „while”, tylko dodatkowo można przy jej tworzeniu zadeklarować wartość i automatycznie dokonywać jej zmiany. Podstawowa pętla „for” ma wygląd:

for(wartość początkowa; warunek; operacja){

ciało pętli

}

Przykład:

for(int liczba = 0; liczba < 10; liczba=liczba+1){
    System.out.println("for: " + liczba + " a teraz string: " + napis);
}

Wynik operacji:

for: 0 a teraz string: xxxxx

for: 1 a teraz string: xxxxx

for: 2 a teraz string: xxxxx

for: 3 a teraz string: xxxxx

for: 4 a teraz string: xxxxx

for: 5 a teraz string: xxxxx

for: 6 a teraz string: xxxxx

for: 7 a teraz string: xxxxx

for: 8 a teraz string: xxxxx

for: 9 a teraz string: xxxxx

Po wszystkich zmianach nasza klasa wygląda tak:

public class PierwszaKlasa {
 public static void main(String[] args) {

  int calkowita; // liczba całkowita bez podanej wartości
  calkowita = 8; // deklaracja naszej liczby
  char znak = 'p'; // znak
  String napis = "xxxxx"; // napis

  System.out.println("liczba: " + calkowita + " a teraz string: " + napis);

  
  while(calkowita > 0){
   System.out.println("while: " + calkowita + " a teraz string: " + napis);
   calkowita = calkowita - 1;
  }
  
  
  for(int liczba = 0; liczba < 10; liczba=liczba+1){
   System.out.println("for: " + liczba + " a teraz string: " + napis);
  }
  
 }
}

Programowanie dla zielonych Cz. 3 „Hello World”

Uruchomienie.

W tej części uruchomimy nasz pierwszy projekt. Z pobranego ostatnio programu wybieramy ikonkę eclipse.exe. Zostaniemy poproszeni o wybranie lokalizacji workspace tzn. miejsca gdzie będą przechowywane nasze aplikacje. Wybór jest dowolny, jak komu wygodnie. Po dokonaniu wyboru zostanie otwarty Eclipse. 

Pierwszy projekt.

Z menu na górze po lewej wybieramy: File -> New -> Project... -> Java Project. Otwarte zostanie okno, w którym wpisujemy nazwę projektu (Project name) np. HelloWorld i klikamy Finish. Właśnie stworzyliśmy pierwszy projekt, który jeszcze nic nie robi. W menadżerze po lewej została dodana nowa ikonka z nazwą naszego projektu. Po jej rozwinięciu widzimy pusty jeszcze folder src, gdzie będą składowane nasze zasoby, oraz plik z bibliotekami. Na razie wystarczą te, które zostały załadowane automatycznie.

Obiektowość.

Na czym polega programowanie obiektowe? W świecie obiektowym wyróżniamy dwie zasadnicze części: klasy i obiekty. Jak pisałem wcześniej obiektem jest wszystko. Człowiek patrząc na samochód bierze go, jako całość, jako jeden obiekt, który może wykonywać różne funkcje i składa się z różnych części, które też są obiektami: koła, silnik itd. Klasa natomiast jest to opis obiektu, jakby jego specyfikacja techniczna, w której jest opisane, z czego co się składa i co może robić. Aby stworzyć obiekt potrzebujemy klasy, żeby go opisać.

Pierwsza klasa.

Aby dodać klasę do naszego projektu klikamy prawym przyciskiem myszy na ikonę projektu w menadżerze, wybieramy New -> Class. W miejscu Name wpisujemy nazwę klasy np. PierwszaKlasa, poniżej zaznaczamy „public static void main(String[] args) „, dzięki czemu zostanie wygenerowana automatycznie pierwsza metoda i klikamy Finish. Metoda, która się pojawiła, czyli „main” jest to punkt startowy programu i wystarczy żeby była tylko jedna w całym projekcie.

Hello World

Stworzyliśmy pierwszy projekt, mamy w nim stworzona pierwszą klasę, czas sprawić, aby coś się działo. Tradycyjnie, jak to jest w każdej książce wypiszemy napis Hello World. W tym celu wystarczy dodać jedną linijkę kodu: „System.out.println("Hello World");” O co dokładnie w tej linijce chodzi nie ma sensu wspominać, ważne jest to, że wszystko, co znajduje się między apostrofami zostanie wypisane i tylko tyle trzeba zapamiętać, bo z tej składni korzysta się baaardzo często. Nasza klasa po dodaniu owej linii wygląda następująco:

public class PierwszaKlasa {
       public static void main(String[] args) {
              System.out.println("Hello World");
       }
}

Odpalamy.

Aby uruchomić program klikamy prawym przyciskiem myszy na ikonkę projektu w menadżerze -> Run As -> Java Application

W konsoli na dole zostanie wyświetlony napis.

Klasa abstrakcyjna a Interfejs

Klasa abstrakcyjna:

Klasa z której nie można utworzyć obiektu. Można po niej dziedziczyć. Może posiadać metody z ciałem lub bez ciała. Używana jest do ogólnej reprezentacji podobnych obiektów.

Interfejs:

Jest to lista metod. W interfejsie metody nie mają ciał, jedynie nazwę, wymagane parametry i typ wartości zwracanej. Interfejsów używa się aby wymóc na klasie go implementującej aby miała napisane wszystkie metody  z tego interfejsu.

Różnice:

Klasa może dziedziczyć  z tylko jednej klasy abstrakcyjnej ale implementować  wiele interfejsów. Wszystkie metody z interfejsu musza się pojawić w klasie go implementującej a podczas dziedziczenia z klasy abstrakcyjnej nic nie musimy, za to już część metod dostajemy w spadku.

Programowanie dla zielonych Cz. 2 „Instalacja”

Od czego zacząć?

„Instalacja” Javy – pobieramy najnowszy JDK, czyli Java SE Development Kit ze strony http://java.sun.com/javase/downloads/widget/jdk6.jsp. Instalujemy paczkę.

Dodajemy zmienne środowiskowe.

W Windows 7: Panel sterowania\System i zabezpieczenia\System -> Zaawansowane ustawienia systemu -> Zmienne środowiskowe

W zmiennych systemowych, pole JAVA_HOME wartość np. C:\Program Files\Java\jdk1.6.0_26 – w zależności gdzie zainstalujemy paczke

IDE

Żeby coś zaprogramować musimy posiadać zintegrowane środowisko programistyczne, czyli tak zwane IDE. W naszym przypadku będzie to Eclipse – czyli obecnie chyba najpopularniejsze IDE. Program można pobrać z http://www.eclipse.org/downloads/. Bez instalowania, wystarczy ściągnąć i już można uruchamiać.

Programowanie dla zielonych Cz. 1 „Co i jak”

Po co uczyć się programowania?

Aby tworzyć. Każdy w dzieciństwie chciał mieć moc tworzenia dowolnych rzeczy z niczego. Teraz żyjemy w takich czasach że możemy to robić. Nie chodzi tu o prace zarobkową, ale o to by móc coś samemu zrobić co ma ręce i nogi. Chociaż często krzywe i owłosione to zrobione przez nas. Dodatkowo sam fakt że coś potrafię jest miły.

Jaki język programowania wybrać?

Na początek proponuje „C”. Język programowania C jest prostym do nauki strukturalnym językiem, który pojawił się już w roku 1972, więc baaaardzo dawno. Ogólnie rzecz ujmując fundamenty świata stoją na C. Da się w nim zrobić prawie wszystko, został rozwinięty do C++ aby zyskać obiektowość. Jest prosty w obsłudze i idealny do nauki.

Dlaczego zatem Java?

Java jest młodsza od C, powstała w 1995 roku i jest jednym z podstawowych języków na świecie, a do tego jest zorientowany obiektowo. Co to oznacza i czym się to różni od strukturalnego C? Otóż w językach strukturalnych lista zadań wykonywana jest po kolei: 1-2-3-4-5….. W obiektówce jest troszkę ciekawiej.  „Wszystko jest obiektem” – ja jestem obiektem, dom jest obiektem, liczba osiem jest obiektem i możemy na siebie oddziaływać. Niby skomplikowane, ale takie nie jest. To jest zdecydowanie bardziej ludzkie niż strukturalność. Zresztą wszystko wyjdzie w praniu.

Czy łatwo jest nauczyć się programować w Javie?

Nawet bardzo łatwo :) Cała ta tajemna sztuka składa się z:

 2 pętli: „for” i „while”,

 warunku „if”,

 instrukcji wyboru „switch”,

struktur grupujących dane: tablic i list

obiektowości świata,

matematyki.

Oczywiście to nie jest wszystko, ale jeżeli już się to opanuje to reszta nie ma znaczenia.

Jak długo trzeba się uczyć żeby programować?

Całe życie oczywiście :), ale żeby sprawdzić czy to nam się podoba wystarczą podstawy czyli dzień może dwa.

Słowa kluczowe

Static – zmienne i metody określone modyfikatorem „static” istnieją zawsze nawet jeżeli nie została utworzona żadna instancja klasy w których jest zadeklarowana. Taka zmienna jest tylko jedna, tzn. jeżeli zmienimy ją w jednym obiekcie zostanie zmieniona jej wartość we wszystkich obiektach tej klasy.

Odwołanie się do zmiennej statycznej wymaga użycia kropki ( NazwaKlasy.NazwaZmiennej)

Final – zmienna zdefiniowana jako „final”, która raz dostała wartość nie może być już zmieniona. Parametry metody z final nie mogą być zmienione. Metoda finalna nie może być nadpisana w sub-klasie.

Synchronized – metoda oznaczona jako „Synchronized” może być wywołana tylko przez jeden wątek w danym czasie.

Kolorowanie składni kodu źródłowego na blogu.

   Aby uzyskać ładne kolory we wstawianych listingach kodów źródłowych i za bardzo się nie namęczyć z własnoręczną edycją napisów korzystam z

  http://google-code-prettify.googlecode.com

Usługa ta automatycznie rozpoznaje jaki język programowania został wybrany i odpowiednio go formatuje.

   Instalacja takiego cudka na stronie jest banalna.

W szablonie strony (w przypadku bloggera Projekt->Edytuj kod HTML) wstawiamy między tagami <head> i </head>

<script src='http://google-code-prettify.googlecode.com/
svn/trunk/src/prettify.js' type='text/javascript'/>
<link href='http://google-code-prettify.googlecode.com/
svn/trunk/src/prettify.css' rel='stylesheet' type='text/css'/>

Natomiast w tagu <body > dodajemy onload='prettyPrint()'

Część mojego szablonu po tych operacjach wygląda następująco:


...
<script src='http://google-code-prettify.googlecode.com/svn/trunk/src/prettify.js' type='text/javascript'/>

<link href='http://google-code-prettify.googlecode.com/svn/trunk/src/prettify.css' rel='stylesheet' type='text/css'/>
</head> 
<body expr:class='&quot;loading&quot; + data:blog.mobileClass' onload='prettyPrint()'>
...

Teraz wystarczy we wpisywanych notkach użyć:
<code class="prettyprint"> …… </code>

Albo aby kod był w ramce:

<pre class="prettyprint"> …… </pre>

W miejsce kropek wstawiając kod źródłowy.

Oczywiście istnieje dużo możliwości konfiguracyjnych naszego formatowania ale na początek wystarczy to.

Plik README projektu znajduje się tutaj