Wymogi formalne projektów

 

Nie zastosowanie się do wymogów formalnych będzie prowadzić do znaczącego obniżenia oceny z projektu, a (w skrajnych przypadkach) nawet do niezaliczenia projektu.

Paczka z projektem

Projekt znajduje się w paczce o nazwie pl.edu.pw.fizyka.pojava.* gdzie * jest identyfikatorem waszego zespołu. 

Nazwy klas

Nazwy klas, interfejsów, typów wyliczeniowych muszą spełniać następujące wymagania:

  • Z dużej litery
  • Pisane UpperCamelCase
  • Nazwy opisują klasę --- nazwa klasy musi informować o jej przeznaczeniu
  • Po angielsku

Poprawne przykłady

  • JButtonOK
  • JFreeChartVelocity
  • DriverManager
  • ComptonExperiment

Niepoprawne przykłady

  • MojaKlasa, EskperymentComptona --- nazwy po polsku
  • Frame, MyFrame --- nazwa nic nie mówi o klasie
  • compton_experiment --- nie pisane camelCase.

Nazwy zmiennych i metod

Nazwy zmiennych i metod powinny spełniać następujące wymagania:

  • Z małej litery
  • Pisane camelCase.
  • Nazwy opisują zmienną
  • Po angielsku

Przykłady poprawne (zmienne)

  • photonEnergyMeV, scatteringAngleDeg
  • ii -- w przypadku zmiennych używanych w pętlach (polecane jest indeksowanie zmiennych zmiennymi dwuznakowymi, ponieważ bardzo ułatwia to wszukanie zmiennej w kodzie).

Przykłady błędne (zmienne)

  • zmienna, i --- nic nie mówi

  • gamma_angle --- nie camelCase

  • katGamma --- po polsku

Nazwy poprawne (metody)

  • computePhotonEnergyMev

Poprawna struktura kodu

Program posiada dobrą strukturę, w której jest podział przynajmniej na:

  • Elementy interfejsu graficznego
  • Model obliczeniowy

Dodatkowo:

  • Funkcje są małe (~ max. 50 linii)

  • Program stosuje się do zasady DRY, czyli struktury danych oraz fragmenty kodu, które są wykorzystywane w wielu miejscach programu, zdefiniowane są w dokładnie jednym miejscu. Potocznie mówiąc: nie ma kopiuj-wklej.

 

Podpisywanie klas

Każda klasa powinna mieć oznaczona autora (jedną z osób w projekcie):

  • Osoba nie będąca autorem będzie otrzymywać prostsze pytania dotyczące danej klasy przy oddawaniu projektu.
  • Dwie osoby mogą być autorem klasy.
  • Klasy nieoznaczone są traktowane tak, jakby autorami były obie osoby.

 

Estetyczny wygląd programu

Program wygląda estetycznie - elementy ułożone tam gdzie powinny być, a nie tam gdzie chciał je ułożyć Layout Manager.

Częste błędy:

  • Pole do wprowadzania danych wejściowych do modelu jest nieproporcjonalnie duże.

  • Program ustawiony jest do działania w okienku o stałym rozmiarze np. 640x480 i nie da się go powiększyć - albo przy powiększaniu powiększają się nie te elementy co trzeba.

    Założenie, że program ma minimalny rozmiar okna jest OK, o ile minimalny rozmiar okna nie jest zbyt duży.

 

Intuicyjność interfejsu

Użytkownik siadając do programu bez czytania instrukcji potrafiłby się nim posłużyć.

Przykłady nieintuicyjnych programów (rzeczywiste błędy studentów):

  • Po wprowadzeniu danych należy w każdym polu wcisnąć klawisz Enter, a dopiero potem guzik start symulacji.
  • Dane należy wprowadzać w konkretnej kolejności inaczej program nie dziala poprawnie.
  • Po włączeniu symulacji, nowe parametry da się wprowadzić dopiero po restarcie programu.
  • Pola tekstowe do wprowadzania danych są nieoznaczone.

 

Dodatkowe uwagi

Należy ponadto unikać poniższych błędów:

W projekcie widać niewyczyszczone ślady pracy nad nim:

  • Dużo zakomentowanego kodu.
  • Program wyświetla na konsolę dużo śmieci.

Program korzysta z wątków niepoprawnie i tą niepoprawność widać bez zaglądania do kodu programu. Na przykład:

  • Długotrwałej symulacji nie da się przerwać bez zamykania programu.
  • Podczas wykonywania obliczeń program się "zacina".

 

 

Wymogi na podstawie opracowania przygotowanego przez J. Bzdak.