Wytyczne do pisania programów

Piotr SzymańskiJęzyk C, Wstęp do informatyki 2009, Laboratorium

Nazewnictwo identyfikatorów

• Należy unikać nic nie mówiących skrótów i nazw skróconycho Źle: int prze(int a);o Dobrze: int isLeap(int year);

• Nazwy złożone z jednej litery, mogą być używane jedynie do:o zmiennych będących licznikami w pętli

np. int i;o zmiennych tymczasowych, których cel jest oczywisty

Nazewnictwo identyfikatorów

• Identyfikatory powinny być nazwane w języku angielskim o Źle: SrAryt(…)o Dobrze: average(…)

• Funkcje zwracajace wartosc logiczna zaczynaja się od is, o Źle: prze(…) lub przest(…);o Dobrze: isLeapYear(…) lub isLeap(…)

• Nazwa identyfikatora musi oddawać jego znaczenie, np.o Źle: prze(int a);o Dobrze: isLeapYear(int year) lub isLeap(int year)

Nazewnictwo identyfikatorów

• Każdy identyfikator składa się z wyrazów (tzw. camelCase):o pierwszego pisanego z małej literyo każdego kolejnego z wielkiej literyo bez oddzielenia, tzn. żadnych podkreśleń albo

myślnikówo Źle: srednia_Ar(…); standodch(…);o Dobrze: average(…) lub standardDeviation(…)

 

Nazewnictwo identyfikatorów

• W danym bloku niedopuszczalne jest powtarzanie nazw identyfikatorówKażdy identyfikator składa się z wyrazów (tzw. camelCase):o Źle:

float najmniejsza(int max,float tablica[]){ float najmniejsza; […];}

o Dobrze: float minimum(float tablica[], int size){ float minElement; […];}

 

Białe znaki

• Tabulacja:o tabulator = 4 spacje

• Należy stosować tylko jedną pustą nową linię w celu odseparowania od siebie treści

• Tylko jedna spacja po danym słowie kluczowym

Rozmiary bloków kodu

• Nie należy przekraczać 76-80 znaków na wiersz

• Pojedyńcza funkcja powinna mieścić się w 40 wierszach, tj. jednym ekranie. o Dopuszczalne są dobrze uzasadnione wyjątki.o Z reguły jednak jeśli funkcja się nie mieści, trzeba lepiej

przemyśleć grupowanie funkcjonalności w funkcje.

Organizowanie w bloki

• Obowiązuje tzw. Allman style (BSD), tj. następujące ułożenie nawiasów i wcięć:• while (x == y)

{something();somethingelse();

}finalthing();

Komentarze

• Komentarze należy umieszczać nad fragmentem, którego dotyczą, ponieważ kod jest z reguły czytany z góry w dół.

• Komentarze należy zaczynać w tym samym pionie co dany kod, np.o Źle:

char* reverseString(char* source); //alokacja stringa

o Dobrze: // ta funkcja alokuje nowego stringa

char* reverseString(char* source);

Treść komentarzy

• Nie komentujcie rzeczy napisanych w kodzie, a ideę stojąca za nimi

• Nie komentujcie rzeczy które są oczywiste bez zajrzenia w treść listy zadań

• Nie komentujcie co robi dana zmienna lub funkcja – to musi wynikać z nazwy!

• Opisując ideę rozwiązania, opisujcie ją na początku funkcji przed jej deklaracją

• Komentarze nie mogą występować co linijkę, w takim wypadku robicie coś źle

Stałe w programach

• Niedopuszczalne jest wpisywanie stałych, które mają jakieś semantyczne znaczenie, "na twardo" w kod, zamiast tego należy je deklarować jako stałe i używać gdzie trzeba, np.o const unsigned int threshold = 30;

float suma = 0;while(suma < threshold){ ...}

o const unsigned int size = 20;char source[size];char dest[size];

Preprocesor a logika programu

• Niedopuszczalne jest stosowanie preprocesora do realizowania logiki programu, a już pod żadnym pozorem do definiowania wyrażeń funkcyjnych. 

• Preprocesor nie sprawdza typów!

Preprocesor przykład

Źle

#define wczyt_sprawdz(typ, dana)

if(scanf(typ, dana)!=1) { printf("Nie podano liczby!\n"); return 1; }

Dobrze

void readVerify(const char* format, void* data, int count){ if( scanf(format, dana)!= count) { printf("Nieprawidłowe wejście!\n");

exit(1); }}

Organizacja funkcjonalności

• Nie należy używać zmiennych globalnych w kodzie.

• Funkcja main służy jedynie do wczytywania danych, sprawdzenia ich poprawnosci i wypisania wyniku.

• Każda funkcjonalność niezwiązana z funkcją main musi być realizowana w osobnych funkcjach.

• Zwracany kod błędu musi być wartością ujemną.

Zmienne globalne - przykład

Źle

char oko,usta;

void rysuj(){ printf("...",oko,oko,usta);}

Dobrze

void drawFace(char eye, char lips){ printf(…, eye,eye,lips);}

Sprawdzanie wejścia - przykład

Źle

temp1=-300.0;scanf("%f",&temp1); if (temp1!=-300)

[…]else

printf("Błąd.\n");

Dobrze

if (scanf("%f",&temp1)!=1){ printf("Błędne wejście.\n"); }

Funkcjonalność - przykład

Źle

int parzy(){    liczba=-1;        printf("Podaj liczbe: ");    scanf("%d",&liczba);    if (liczba!=-1) return ((rok%2==0));        return -1;}

int main(){  int r;  printf("Podaj liczbe:\n");  scanf("%d",&r);  if (((r%2==0)) /* warunek na parzystość*/    {      printf("Liczba %d jest parzysta.\n",r);    }    else     {        printf(" Liczba %d jest nieparzysta.\n", r);    }   return(0);}

Dobrze

int isEven(int number){   return (number % 2 == 0);    }

int main(){  int number;  printf("Podaj liczbę:\n");  scanf("%d",&number);

  printf(“Liczba %d jest ", number);

  if (isEven(number))   {      printf(“parzysta.\n");  }  else   {        printf("nieparzysta.\n”);  }   return 0;}

Kolejność argumentów

• Przyjęto w języku C następującą tradycyjną kolejność argumentów w funkcjach pracujących na tablicach:1. Tablica docelowa2. Tablica źródlowa3. Rozmiar danych

– Źle:float najmniejsza(int max,float tablica[])Dobrze: float minimum(float data[], int max)

Zakres obowiązywania

• Zasady te obowiązują w stosunku do wszystkich list i kolokwiów

• Rozwiązania nie przestrzegające tych zasad nie będą zaliczane, są takim savoir-vivre programowania

• Nieprzestrzeganie tych zasad na kursie doprowadzić może tylko do jego niezaliczenia, w pracy natomiast możecie skończyć na bezrobociu i kiepską opinią w branży.