Regulament coding style

Responsabili:

Modificări și actualizări
  • 6 Martie
    • finisat checker
  • 21 Martie
    • încărcat regulament
  • 12 Aprilie
    • excluderea check-ului de header guard
  • 27 Aprilie
    • includerea opțiunii de a folosi ref ca valori de return în funcții

Obiective

În urma parcurgerii și respectării acestui regulament:

  • veți înțelege conceptul de clean code;
  • veți putea identifica coding style-ul vostru;
  • vă veți îmbunătăți modul de a scrie cod pentru a-l face mai ușor de citit și înțeles de cei din jur.
  • vă veți acomoda cu coding style-ul folosit la Google.

Conceptul de clean code

Cuvântul care definește cel mai bine codul curat este consistența.

Prin consistență înțelegem “ceva” care nu se schimbă, care este impus respectă același set de reguli. Din acest motiv, creați-vă un coding style al vostru adică aplicați un set de reguli definite (de voi) pe tot parcursul temei, încă de la început.

Nu vă bazați pe factorizare, poate consuma destul de mult timp – în unele cazuri, chiar mai mult decât rezolvarea în sine a temei.

Păstrați-vă coding style-ul pentru fiecare temă sau proiect în care lucrați. Doar așa rămâneți consistenți.

Reguli

Variabile

Nu putem rezolva o temă fără variabile așa că de ce să nu le utilizăm corect. Exemplu: Nimeni nu ar înțelege ce face o variabilă zxc.

Reguli generale și referințe:

  • Folosiți variabile locale oriunde în mod corect deoarece până și locul declarării lor este foarte important;

Nu folosiți variabile globale. Iată de ce.

  • Atenție mare la pointeri.
  • Folosiți denumiri care descriu folosința variabilei.
  • Nu comentați variabilele decât în cazuri extreme.
    • De exemplu inițializarea unei variabile statice cu o valoare rezultată dintr-un calcul.
  • Evitați repetițiile:
int valueForBitEncryption;

vs.

int intValueForBitEncryption;
int i = 0;
double x = 0.00;
char c = '\0'; 

Funcții și metode

  • O funcție ar trebui să facă un singur lucru. Și să îl facă bine.

O funcție care face un singur lucru este în primul rând mult mai ușor de testat. În plus, este mult mai eficient atât din punct de vedere al performanțelor cât și al timpului să testați corect fiecare etapă parcursă în rezolvarea unei probleme. De exemplu, când primiți segmentation fault, în momentul în care folosiți gdb acesta vă returnează (ierarhic) funcția în care primiți eroarea. Comparați o funcție de 200 de linii care la un moment dat întoarce un segmentation fault sau o colecție de 10 funcții (care fac exact același lucru ca și cea de 200 de linii) dintre care doar una întoarce segmentation fault.

  • Într-un cod modularizat este mult mai ușor de depanat erori sau comportament greșit.

Reguli generale și referințe:

  • numărul de linii corect ;
  • aplicați principiul de supraîncărcare din C++ nu doar la operatori, cât și la funcții;
  • denumiți-vă funcțiile cât mai sugestiv însă fără a oferi informații în plus;
    • opțional: folosiți acest tip de comentarii pentru a descrie informații care nu sunt subînțelese;
  • folosiți funcții ajutătoare și creați-le cât mai generale (să poată fi aplicate pe mai multe cazuri, nu doar pe cel curent - vezi aici;
  • apelați funcțiile în mod corect; în plus, folosiți variabile locale pentru claritate;
    • C++ oferă posibilitatea trimiterii parametrilor pe mai multe linii.
  • la fel și în cazuri expresiilor booleene.
  • folosiți parametrii ca input și valorile de return ca output:
  • Folosiți clase și obiecte pentru a lucra cu mai multe câmpuri/informații.

Clase și structuri

Alegeți clasele și obiectele în locul structurilor. Ați învățat în laboratorul 1 de ce.

Reguli generale și referințe:

  • Denumiți corect atât clasele cât și atributele lor folosind nume care vă vin în minte evidențiază rolul lor.
    • Astfel, nu aveți nevoie de comentarii de clasă iar codul arată mult mai aerisit.
    • Folosind litere mari pentru clase evitați erori rezultate în urma încercării intanțierii unui obiect cu o metodă, de exemplu.

Nu folosiți variabile globale. Iată de ce.

Formatare

Nu folosiți un singur fișier pentru întreaga rezolvare.

Folosiți fișierele .h pentru orice definirea claselor iar fișierele .cpp doar pentru funcția main pentru implementări. O pereche de fișiere .h - .cpp ar trebui să definească o singură clasă. Puteți folosi și fișiere tip helpers pentru funcții ajutătoare.

Reguli generale

Codul poate deveni derutant când apare o greșeală gramaticală ce poate îndruma cititorul spre o idee/cale greșită.

Puteți folosi fie tab-uri fie spații albe pentru alinierea orizontală.

Rularea checker-ului de coding style

Descărcați arhiva cu checker-ul de coding style, dezarhivați-l în directorul dorit și rulați comanda utilizând ca director directorul în care aveți fișierele temei:

 ./checker.sh director 

Puteți descărca checker-ul separat și de aici:

codingstylecheckerv4.zip

Acordarea punctajului

Bonusul se acordă procentual cu numărul testelor trecute. Dacă ai obținut maxim pe temă și nu există erori de coding style, vei obține bonusul de 0.2p. În schimb, dacă îți trec doar 50% din teste și nu ai erori de coding style vei obține doar 0.1p bonus. În cazul erorilor de coding style bonusul va fi 0p.

Recomandări

Țineți cont de erorile de coding style încă de la început pentru a evita un număr mare de erori la finalul temei.

Bibliografie

sd-ca/2017/regulament-checker.txt · Last modified: 2017/12/12 14:52 by teodora.serbanescu
CC Attribution-Share Alike 3.0 Unported
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0