System Obsługi Szpitala, sos



Pobieranie 131,67 Kb.
Data15.04.2018
Rozmiar131,67 Kb.

System Obsługi Szpitala (SOS)

Wersja: 1.1

Konwencje programistyczne

Data: 25/08/2001





Konwencje programistyczne
Wersja 1.1

Historia zmian


Data

Wersja

Opis

Autorzy

31/07/2001

0.9

Wstępna wersja Konwencji programistycznych

Maciej Bajołek

Artur Kaszczyszyn



25/08/2001

1.0

Konwencje programistyczne

Maciej Bajołek

Artur Kaszczyszyn



31/09/2001

1.1

Konwencje programistyczne. Zmiana struktury dokumentu. Dodanie nowych reguł. Zmiana reguł dotyczących EJB.

Maciej Bajołek

Artur Kaszczyszyn
















Spis treści

1. Wstęp 4

1.1 Cel 4

1.2 Bibliografia 4

2. Formatowanie kodu 4

2.1 Wcięcia 4

2.2 Odstępy w postaci białych znaków 5

2.3 Wyrażenia 6

2.3.1 Wyrażenie return 6

2.3.2 Wyrażenie if-else 7

2.3.3 Wyrażenie while 7

2.3.4 Wyrażenie do-while 7

2.3.5 Wyrażenie for 7

2.3.6 Wyrażenie switch 8

2.3.7 Wyrażenie try-catch 8

2.4 Deklaracje 9

2.4.1 Deklaracja zmiennych 9

2.4.2 Deklaracja metod 9

2.4.3 Deklaracja klas 10

3. Dokumentowanie kodu 10

4. Konwencje nazewnicze 11

4.1.1 Wybór nazw 11

4.1.2 Nazwy dla metod set/get oraz set/is 11

4.1.3 Nazwy pakietów 12

4.1.4 Nazwy klas i interfejsów 12

4.1.5 Nazwy metod 13

4.1.6 Nazwy zmiennych 13

4.1.7 Nazwy stałych 13

4.1.8 Nazwy dla EJB 13

4.1.9 Nazwy dla bazy danych 15

4.1.10 Nazwy stron HTML i JSP 17

4.1.11 Akronimy i skróty 17

5. Konwencje programistyczne 17

5.1 Wyjątki 17

5.2 Debugowanie 18

5.3 Programowanie HTML/JSP/Serwletów 18

5.4 Programowanie baz danych 18

5.5 Inne reguły programistyczne 19



Konwencje programistyczne

  1. Wstęp

    1. Cel


Dokument stanowi próbę ustalenia konwencji nazewniczych i reguł programowania dla celów implementacji systemu SOS.


    1. Bibliografia


Konwencje programistyczne

http://www.ambysoft.com/javaCodingStandards.html

http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Konwencje dokumentacyjne

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

  1. Formatowanie kodu

    1. Wcięcia


  • pliki źródłowe nie powinny być dłuższe niż 2000 linii

  • linie programu nie powinny być dłuższe niż 80 znaków

Linie programu o długości większej niż 80 znaków powinny być łamane według następujących zasad:

  • łam linie po przecinku

public void doSomething(String parameter1, String parameter2,

String parameter3) throws Exception {

statements;

}


  • łam linie przed operatorem

variable = variable1 * (variable2 – variable3 + variable4)

+ variable5 * variable6;
if ((condition1 && condition2)

|| (condition3 && condition4)) {

statements;

}


  • złamane linie wcinaj o kilka tabulacji, aby kod stał się przejrzysty



  • dla wcięć używaj tylko i wyłącznie tabulacji o rozmiarze 4 znaków

Nie używaj spacji. Używany przez siebie edytor dostosuj do tej konwencji.

    1. Odstępy w postaci białych znaków


  • słowo kluczowe, po którym występuje nawias otwierający powinno być od niego oddzielone spacją

if (condition) {

statements;

} else {


statements;

}
a nie tak


if(condition) {

statements;

} else {

statements;

}
Spacja nie powinna jednak pojawić się pomiędzy nazwą metody a jej nawiasem otwierającym. Taka konwencja pozwala rozróżnić słowa kluczowe od wywołań metod.


  • spacja powinna pojawić się po przecinkach w liście parametrów funkcji

  • spacja powinna oddzielać operatory od operandów

Wyjątkiem są tutaj operatory unitarne: minus, inkrementacji i dekrementacji.
variable1 += varaible2 + variable3;

variable++


a nie tak

variable1+=variable2+variable3;

variable ++;


  • spacja powinna oddzielać składniki występujące w wyrażeniu for

for (initialization; condition; update) {

statements;

}


  • spacja powinna oddzielać operator rzutowania od rzutowanego wyrażenia

(int) variable

a nie tak
(int)variable



  • nie umieszczaj odstępu pomiędzy nawiasami początkowym i końcowym funkcji czy wyrażeń

public void doSomething(String parameter) {

statements;

}
a nie tak


public void doSomething( String parameter ) {

statements;

}


    1. Wyrażenia

      1. Wyrażenie return


Nie należy używać nawiasów okrągłych przy wyrażeniu return przy zwracaniu pojedynczej wartości. Można ich użyć ewentualnie wówczas, gdy zwracamy bardziej skomplikowane wyrażenie.

return name;


return ((name != null) ? name : defaultName);

      1. Wyrażenie if-else


Wyrażenie if-else powinno mieć postać:

if (condition) {

statements;

} else {


statements;

}

Przy wyrażeniu if należy zawsze używać nawiasów klamrowych.



if (condition) {

statement;

}
a nie tak
if (condition)

statement;



      1. Wyrażenie while


Wyrażenie while powinno mieć następującą postać:
while (condition) {

statements;

}

      1. Wyrażenie do-while


Wyrażenie do-while powinno mieć następującą postać:

do {


statements;

} while (condition);



      1. Wyrażenie for


Wyrażenie for powinno mieć następującą postać:
for (initialization; condition; update) {

statements;

}

      1. Wyrażenie switch


Wyrażenie switch powinno mieć następującą postać:

switch (condition) {

case 1:

statements;



/* falls through */

case 2:


statements;

break;


case 3:

statements;

break;

default:


statements;

break;


}
Jeśli dana opcja case nie posiada wyrażenia break, wówczas w jego miejsce należy wstawić komentarz. W powyższym przykładzie tym komentarzem jest /* falls through */

Każde wyrażenie switch powinno zawierać opcje default, nawet pustą. Wyrażenie break


w opcji default jest nadmiarowe, ale pozwala zapobiec błędom, jeśli później po opcji default zostanie dodana nowa opcja case.

      1. Wyrażenie try-catch


Wyrażenie try-catch powinno mieć następującą postać:
try {

statements;

} catch (Exception ex) {

statements;

} finally {

statements;

}

    1. Deklaracje




      1. Deklaracja zmiennych


  • deklaruj jedną zmienną w linii

String variable1;

String variable2;
a nie tak

String variable1, variable2;



      1. Deklaracja metod


  • deklaruj puste metody w postaci

public void doSomething() {}
a nie tak

public void doSomething() {}



public void doSomething(String parameter1, String parameter2) {}


a nie tak
public void doSomething(String parameter1,parameter2) {}


  • nie używaj niepotrzebnych białych znaków w deklaracji metody

Nawias otwierający listę parametrów metody nie powinien być oddzielony żadna przerwa od nazwy metody.

Pomiędzy nawiasem otwierającym a pierwszym parametrem metody nie powinno być żadnej przerwy (podobnie dla ostatniego parametru i nawiasu zamykającego)


public void doSomething(String parameter2, String parameter2) {}

a nie tak


public void doSomething ( String parameter1, String parameter2 ) {}


  • metoda rzucająca wyjątek powinna być zadeklarowana w postaci

public void doSomething() throws Exception {

statements;

}


  • nie deklaruj metod, które mają więcej niż 4-5 parametrów.



      1. Deklaracja klas


  • klasę rozszerzająca inną klasę lub implementującą jakiś interfejs zadeklaruj w postaci

public class SomeClass extends OtherClass {

statements;

}

  1. Dokumentowanie kodu


Dokumentowanie kodu jest rzeczą niezbędną w każdym komercyjnym projekcie informatycznym. Późniejsze zrozumienie kodu oraz jego ewentualne zmiany są możliwe jedynie wówczas, jeśli ma się do czynienia z kodem dokładnie udokumentowanym.

Dokumentowanie kodu pozwala na wygenerowanie dokumentacji do kodu w formacie HTML


z wykorzystaniem narzędzia javadoc z J2SE.

Wymagania dotyczące dokumentowaniu kodu są następujące:



  • komentarze powinny być pisane wyłącznie w języku angielskim

  • komentarze powinny dotyczyć klas, interfejsów, metod oraz zmiennych

  • komentarze powinny być sporządzane zaraz po napisaniu kodu.

Jeśli nie opisze się nowej klasy, metody i zmiennej zaraz po jej wprowadzeniu, wówczas szanse na to, że zostanie to zrobione w późniejszym czasie są praktycznie zerowe.

Nie ma bowiem niczego bardziej nieciekawego i nudnego jak powracanie do napisanego wcześniej kodu i dokumentowanie go.



  • informacje o tym jak należy sporządzać komentarze są dostępne pod adresem

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html



  • dokumentowanie klas

Przed każdą klasą powinien pojawić się komentarz mówiący o umiejscowieniu klasy
w architekturze systemu, jej celach, relacjach z innymi klasami (znacznik @see). Umieścić należy tutaj również znaczniki mówiące o autorach danej klasy (znacznik @author) oraz wersji danej klasy (@version)

  • dokumentowanie metod

Przed każdą metodą powinien pojawić się komentarz mówiący o funkcjonalności danej metody, przyjmowanych przez nią parametrach (znacznik @param), zwracanej wartości (znacznik @return), rzucanych wyjątkach (znacznik @exception lub @throws), odwołaniach do innych metod czy klas (znacznik @see)


  • dokumentowanie zmiennych i stałych

Dla stałych i zmiennych dodaj krótkie objaśniające komentarze.

  • dodatkowe komentarze

Komentarze powinny również pojawić się dodatkowo w tych miejscach kodu, który wymaga dodatkowych opisów i wyjaśnień.

  • nagłówki plików projektowych

Każdy plik projektu, czy to konfiguracyjny, czy źródłowy klasy, czy w końcu JSP powinien posiadać nagłówek informacyjny. Nagłówek informacyjny zawiera dane na temat projektu i firmy, bądź organizacji realizującej ten projekt

Nagłówek powinien być zakomentowany w kodzie zgodnie z regułami obowiązującymi dla danego typu pliku



  1. Konwencje nazewnicze




      1. Wybór nazw


Zwracaj szczególną uwagę na wprowadzane nazwy pakietów, klas, metod i zmiennych. Nazwa klasy czy metody powinna być tak wybrana aby łącznie z dołączonym do nich komentarzem pozwalały na zorientowanie się w ich działaniu bez konieczności wnikania w szczegóły implementacyjne. Pozwala to na zapoznanie się z kodem napisanym przez drugą osobę znacznie szybciej.
      1. Nazwy dla metod set/get oraz set/is


Nazwy dla metod get/set powinny być zgodne z konwencją nazewniczą obowiązującą dla Java Beans.

private String name;


public String getName() {

return name;

}
public void setName(String name) {

this.name = name;

}

Podobnie jest w przypadku metod set/is.


private boolean default;
public boolean isDefault() {

return default;

}
public void setDefault(boolean default) {

this.default = default;

}

      1. Nazwy pakietów


  • nazwa pakietu pisana jest małymi literami.

  • jeśli nazwa pakietu składa się z wielu słów, to wówczas nie wprowadza się między nimi żadnego separatora

package edu.agh.hss.ejb.creditcard

a nie tak

package edu.agh.hss.ejb.credit_card


  • nazwa pakietu powinna odpowiadać następującemu szablonowi:

..
.

gdzie


- nazwa domeny najwyższego poziomu: com, edu, gov, mil, net, org lub dwuliterowy kod kraju zdefiniowany w normach ISO.

- nazwa firmy lub organizacji realizującej dany projekt

- nazwa projektu



- nazwa modułu projektu

Kolejne elementy nazwy pakietowej są już dowolne.

Przykładem poprawnie zdefiniowanej nazwy pakietowej jest więc

package edu.dsrg.hss.ejb


      1. Nazwy klas i interfejsów


Nazwa klasy i interfejsu może być złożona z jednego lub wielu słów. Przy czym każde ze słów składowych musi rozpoczynać się dużą litera. W nazwach klas i interfejsów nie należy używać skrótów lub akronimów chyba że są one znacznie bardziej rozpowszechnione niż ich pełne nazwy np. URL, HTML

public class SomeClass {


}
      1. Nazwy metod


Nazwy metod mogą się składać z jednego lub wielu słów. Przy czym każde ze słów składowych,
z wyjątkiem pierwszego, musi rozpoczynać się dużą litera

public void doSomething() {


}

      1. Nazwy zmiennych


Nazwa zmiennej może się składać z jednego lub wielu słów. Przy czym każde ze słów składowych,
z wyjątkiem pierwszego, musi rozpoczynać się dużą litera.

private User user;


Jeśli mamy do czynienia z jakąkolwiek kolekcja obiektów wówczas nazwa zmiennej powinna być pisana w liczbie mnogiej

private Collection users;


      1. Nazwy stałych


Nazwa stałej może się składać z jednego lub wielu słów. Każde ze słów pisane jest dużymi literami. Słowa oddzielone są od siebie znakiem podkreślenia.
public static final NEW_LINE = ”\n”;

      1. Nazwy dla EJB


Nazwy dla Entity Beans:

  • remote interface: EB

np. UserEB

  • local interface: EBLocal

np. UserEBLocal

  • home interface: EBHome

np. UserEBHome

  • home local interface: EBLocalHome

np. UserEBLocalHome

  • bean class: EBImpl

np. UserEBImpl

  • primary key class: Key

np. UserKey

  • dao class: DAO

np. UserOracleDAO, UserSybaseDAO

Nazwy dla Session Beans:



  • remote interface: SB

np. UserSB

  • locale interface: SBLocale

np. UserSBLocale

  • home interface: SBHome

np. UserSBHome

  • home local interface: SBLocalHome

np. UserSBLocalHome

  • bean class: SBImpl

np. UserSBImpl

Nazwy dla Message Driven Beans:



  • bean class: MDBImpl

np. UserMDBImpl

Nazwy dla metod find:



EB findBy() {

}

np.



UserEB findByName(String name) {

}


  • jeśli metoda find zwraca kolekcję interfejsów local lub remote to nazywamy ją zgodnie ze schematem

EB findAllBy() {

}
np.

Collection findAllByRole(int role) {

}

      1. Nazwy dla bazy danych


  • nazwy tabel, widoków, sekwencji i wszelkich innych obiektów bazodanowych są pisane wyłącznie w języku angielskim

  • wszystkie nazwy są pisane małymi literami

  • nazwy tabel rozpoczynają się od t_

np. t_user

  • nazwy sekwencji rozpoczynają się od s_

np. s_user

  • nazwy widoków rozpoczynają się od v_

np. v_user

  • nazwy indeksów rozpoczynają się od i_

np. i_user_1, i_user_2

  • nazwy więzów integralności typu klucz podstawowy rozpoczynają się od pk_

np. pk_user

  • nazwy więzów integralności typu klucz obcy rozpoczynają się od fk_

np. fk_user_1, fk_user_2

  • nazwy składające się z wielu słów buduj oddzielając każde z nich znakiem podkreślenia

np. t_aparatus_type

  • każda tabela powinna posiadać klucz główny w postaci pola identyfikatora noszącego po prostu nazwę id.

  • dla każdej tabeli definiuj raczej osobną sekwencję stanowiącą źródło wartości dla jej klucza głównego

  • używaj dużych liter dla słów kluczowych SQL

Reguła ta dotyczy zarówno wyrażeń SQL znajdujących się w kodzie Javy jak i skryptach tworzących bazę danych czy operujących na niej.
SELECT name FROM t_user;
a nie tak
select name from t_user;


      1. Nazwy stron HTML i JSP


Nazwy stron pisz małymi literami. Nazwy stron składające się z wielu słów oddzielaj znakiem podkreślenia, np. user_login.jsp
      1. Akronimy i skróty


Skróty w nazwach klas, interfejsów, metod i zmiennych powinny być pisane małymi literami
z wyjątkiem pierwszej litery skrótu.

Akronimy natomiast powinny być pisane w całości z dużej litery, np. HTML, URL.



  1. Konwencje programistyczne

    1. Wyjątki


  • dla oznaczenia wyjątku nie używaj wartości zwracanej poprzez wyrażenie return.

Zamiast tego wyrzucaj odpowiedni wyjątek.


  • nigdy nie używaj System.exit() w obsłudze wyjątku w klasie lub metodzie gdzieś na niskim poziome. Zamiast tego wyrzucaj odpowiedni wyjątek wyżej, gdzie zostanie on odpowiednio obsłużony.



  • nigdy nie umieszczaj w kodzie nie obsłużonego wyjątku

try {


statements;

} catch (Exception ex) {

/* TODO */

}


  • zmienną określającą wyjątek oznaczaj poprzez ex, chyba, że taka nazwa jest już wykorzystywana



    1. Debugowanie


  • do celów logowania i debugowania nie używaj System.out czy System.err. Zamiast tego posługuj się odpowiednimi metodami pakietu Log4j . Jeśli pakiet Log4j nie jest zainicjowany wówczas do celów logowania używaj innego mechanizmu (np. servlet API)

  • komentarze dla celów debugowania powinny być pisane tylko w języku angielskim

Nie należy używać polskich komentarzy.

  • komentarze powinny być raczej krótkie, ale za to jasne i niosące wystarczająco informacji do ewentualnego wyśledzenia błędu lub opisania zaistniałej sytuacji



    1. Programowanie HTML/JSP/Serwletów


  • znaczniki HTML i JSP pisz z malej litery

  • wartości atrybutów w HTML i JSP ujmuj w znaki cudzysłowu

  • w obiekcie HttpSession nie przechowuj dużych obiektów ani grafu obiektów. Zamiast tego przechowuj w sesji referencję do entity beana reprezentującego dany obiekt.

  • usuwaj obiekty z sesji jeśli nie są już potrzebne

  • usuwaj obiekt samej sesji poprzez wywołanie HttpSession.invalidate() w miejscu odpowiadającym za wylogowanie użytkownika z aplikacji

  • jeśli strona JSP nie używa informacji zawartych w sesji zabroń jej pobierania referencji do obiektu sesji poprzez dyrektywę

<%@ page session=”false” @>

    1. Programowanie baz danych


  • nie dokonuj konkatenacji stringów w wyrażeniu SELECT–FROM–WHERE
    (czyli nie używaj operatora + w tego typu wyrażeniach). Zamiast tego posługuj się PreparedStatement. Jest to sposób znacznie wydajniejszy z punktu widzenia bazy danych.

String sql = „SELECT name FROM t_user WHERE surname = ?”;

PreparedStatement ps = con.prepareStatement(sql);

ps.setString(1, surname);


a nie tak
String sql = “SELECT name FROM t_user WHERE surname = “ + surname;

Statement stmt = con.createStatement();

Stmt.executeQuery(sql);


  • nigdy nie używaj * w wyrażeniach SQL. Zamiast tego wypisuj wszystkie wyciągane z danej tabeli pola

SELECT name, surname FROM t_user;


a nie tak
SELECT * FROM t_user;


  • zamykaj poprawnie wszystkie otwarte PreparedStatement po ich użyciu.

Każdy otwartemu PreparedStatement odpowiada bowiem w bazie danych otwarty kursor. Może bowiem dojść do sytuacji, w której dojdzie do ich wyczerpania.

    1. Inne reguły programistyczne





  • stałe numeryczne i znakowe nie powinny być umieszczane w kodzie bezpośrednio. Zamiast nich powinny się pojawić odpowiednio zdefiniowane stałe




  • zamiast Vector używaj Collection (ArrayList)

Collection list = new ArrayList();




  • zamiast Enumeration używaj Iterator

Iterator it = list.iterator();

while (it.hasNext()) {

User user = (User) it.next();

...

}
lub tak


for (Iterator it = list.iterator(); it.hasNext();) {

User user = (User) it.next();

...

}


  • w operacjach na stringach używaj klasy StringBuffer zamiast String, bo jest bardziej efektywna




  • nie używaj zmiennych public, które nie są public static final. Zamiast nich zdefiniuj zmienną prywatną i dodaj do klasy metody set/get lub set/is dla tej zmiennej.




  • każdy obiekt trzymający dane powinien definiować metodę toString() wypisującą jego aktualny stan. Powinien również przeciążać metody hashCode() oraz equals(), aby pracowały na jego atrybutach

public String toString() {

StringBuffer sb = new StringBuffer();

sb.append(“[ Hospital: “ + “\n”);

sb.append(“name : “ + name + “\n”);

sb.append(“]”);


return sb.toString();

}


  • importując pakiety na początku pliku źródłowego nie używaj znaku *. Zamiast tego nazywaj każdą wykorzystywaną klasę osobno

import java.util.Vector;

import java.util.Iterator;
a nie tak
import java.util.*;



  • używaj this w konstruktorze klasy i nazywaj parametry przekazywane do konstruktora tak, jak nazwy zmiennych przechowywanych w klasie

public doSomething(String name) {

this.name = name;

}


  • staraj się unikać tzw. efektów ubocznych (ang. side effects), a jeśli już takie występują
    w twoim kodzie dokumentuj je bardzo dokładnie

Przez efekty uboczne rozumiemy np. robienie w metodach get/set czegoś więcej niż tylko zwracanie lub ustawianie jakieś zmiennej.


Copyright  Distributed Systems Research Group. All Rights Reserved

z







©operacji.org 2017
wyślij wiadomość

    Strona główna