Responsabili:

• Darius Neațu (2018, 2019)
• Dorinel Filip (2018, 2019)

Această pagină are o importanță deosebită pentru modul vostru de formare ca programatori. Vă rugăm să o citiți integral!

Este foarte important să putem scrie cod corect, eficient, dar, în aceeași măsură, codul nostru trebuie să poată fi înțeles și de alte persoane.

Imaginați-vă următoarele scenarii: 1. 2 colegi scriu cod în maniere cu totul diferite, iar la un moment dat trebuie să îl combine pentru a face produsul final. Deoarece nici unul nu înțelege ce a făcut celălalt pentru că au scris cod cum au vrut, acum sunt nevoiți să stea și să facă modificări astfel încât să ajungă la un numitor comun și să poată colabora. Nu era mai bine ca fiecare să fi urmat aceleași convenții de la bun început?

2. Un alt scenariu, mai aproape de voi, este chiar acum când voi scrieți primele programe în C. Se întămplă (și este normal) să uităm anumite lucruri o dată cu trecerea timpului, prin urmare voi veți simți nevoia să vă uitați pe programele scrise de voi (ex. cum aloc dinamic un tablou 3D în C, cum am rezolvat tema X care avea o idee asemănătoare cu ce îmi trebuie mie acum). Ce se va întâmpla dacă nu aveți un coding style adecvat? Răspunsul este simplu: nu veți înțelege propriu cod! Pentru lucrurile simple evident că trebuie să treaca un timp destul de lung, dar pentru cele grele și foarte grele puteți ajunge în situația în care să “uitați” cum se codează o chestie de pe o zi pe alta.

Toate scenariile de mai sus reprezintă exemple care v-ar putea afecta în sens negativ, de aceea la materia PC (și multe altele în facultate) vi se va impune să urmăriți anumite aspecte care să vă obisnuiască încă de la început, când lucrurile sunt foarte simple, astfel încât aceste deprinderi să intre în modul vostru normal de a coda.

Cum rezolvăm problemele de mai sus? Scenariul 2 se poate rezolva prin a scrie într-un mod ordonat, propriu, codul. Este de ajuns? Răspunsul este nu, întrucât e foarte puțin probabil să scrii cod de unul singur tot timpul. Colaborarea este un lucru care va veni la un moment dat în ajutorul vostru.

Pentru a rezolva toate problemele care pot apărea, vom folosi o convenție de coding style. Convențiile sunt seturi de reguli acceptate de comunități largi. Există mici diferențe între ele, fapt care face ca atunci când se trece de la o convenție la alta (ex. alta firmă) să nu reprezinte o problemă.

La Programarea Calculatoarelor seria CA vom folosi o convenție de coding style extrasă din documentația oficială de C++ de la Google (Google C++ ). Motivele pentru care am ales-o este că este larg folosită de comunitatea open-source, oferă un script automat de testare care afisează toate problemele pentru a le corecta, iar acest script poate fi ușor adaptat de la C++ la C.

Vom încerca să enumerăm lucrurile pe care trebuie să le aveți in vedere, apoi vom trece prin toate instrucțiunile limbajului C și vom da exemple.

* Codul trebuie să fie:

• clar și modularizat
  • Codul se va împărți în componente astfel încât să existe o separație logică (ex. mai multe fișiere, mai mule funcții etc). Fiecare bucată elementară de logică va fi mutată într-o funcție (ceea ce permite și reutilizarea codului. Funcțiile care au ceva în comun (ex. funcții matematice) vor fi grupate.
• expresiv
  • Numele entităților trebuie să fie sugestive.
    • Numele de variabilă trebuie să fie sugestiv și să arate la ce e folosită aceea variabilă. Este perfect ok să avem nume precum i, j, k, p, q pentru indecsi/contori folosiți atunci cand lucrăm cu tablouri, dar pentru lucruri netriviale, numele de variabilă trebuie să arate mai mult (ex. int count_duplicates; vs int c; - prima situatie exprima clar ca acest contor este folosit pentru a număra duplicatele, în schimb în cea dea doua situație nu putem înțelege la ce e folosit c fara a citi tot codul care îl folosește).
    • Numele de funcții reflectă de asemenea acțiunea pe care aceasta o realizează. Exemplu: int count_duplicates(int n, int v[NMAX]); vs int f(int n, int v[NMAX]);. Primul caz spune ce face funcția, în cel de-al doilea caz numele funcției nu ne spune nimic.
      • Convenție: numele de variabile și funcții vor fi sugestive, vor fi compuse din litere mici, cifre si underscore (în cazul in care dorim să avem mai mult cuvinte).
  • Comentariile ajută la îmbunătățirea expresivității, atunci când numele și organizarea codului nu sunt suficiente. Exemplu: o funcție care care caută duplicatele dintr-un vector, apoi șterge elementele duplicate, iar din cele ramăse le șterge pe toate pare sau divizibile cu 1007 și returnează și câte numere sunt prime. Nu putem exprima întreaga funcționalitate doar prin numele funcției, astfel că o vom numi update_array, iar înainte de semnatura funcției vom explica algoritmul de update în câteva cuvinte.
• lizibil
  • O componentă foarte importantă o reprezintă spațierea. Codul trebuie să fie cât mai aerisit (să conțină spații, linii goale unde e cazul).
  • Funcțiile nu trebuie să fie foarte lungi (maximum 80 de linii în C), liniile nu trebuie să fie foarte lungi (maximum 80 de caractere pe linie în C).
  • Indentarea joacă un rol foarte important. De fiecare dată când se deschide o pereche de acolate (”{}”), în interiorul lor codul se indenteaza cu un tab (4 spații) mai la dreapta.

Cititi exemplele cu if-else de mai jos si analizati:

• spatierea (if spatiu (; spațiu operator spațiu; etc)
  • Pentru operatorii binari avem convenția: operand1 spatiu operator spatiu operand2. (Ex. “x + 2”, int x = y + 2;”)
  • Pentru operatorii unari nu lăsăm spațiu între operator și operand. (Ex. “i++”, ”++i”).
  • Nu lăsăm spațiu niciodată înainte de punct și virgulă.
  • Lăsăm spațiu mereu după virgulă, niciodată înainte.
• identarea (de fiecare data când se intră în {} se scrie cu un tab mai la dreapta)
• cum se închid și deschid acoladele
  • chiar dacă avem o singură instrucțiune în if și nu e nevoie să punem acolade, în convenția stabilită vom pune pentru a pastra aspectul unitar al codului; un alt motiv ar putea fi acela că putem adăuga direct intrucțiuni noi fără să omitem din greșeală să mai punem și acolade.
• cum se scrie o cascadă de if-else if-uri

if (condition) {
    printf("Gigel!\n");
}
...
if (n % 2 == 0 && n > 10 && (n % 3 == 1 || n % 7 == 2)) {
    ...
}
...
 
if (condition) {
    ...
} else {
    ...
}
 
...
if (condition1) {
    ...
} else if (condition2) {
    ...
} else if (condition3) {
    ...
} else {
    ...
}

Citiți exemplele cu for de mai jos și analizați

• spațierea
• identarea (de fiecare dată când se intră în {} se scrie cu un tab mai la dreapta)
• cum se închid și deschid acoladele
• cum se scriu for-uri imbricate

for (int i = 0; i <= n; ++i) {
    printf("%d", i);
}
 
...
for (int i = n; i >= 0; --i) {
    printf("%d", i);
}
 
...
 
int found = 0;
for (int i = n; i >= 0 && !found; i -= 2) {
    ...
    if (...) {
         printf("%d", i);
         found = 1;
    }
}
 
...
 
for (int i = 3; i * i <= n; i += 2) {  // i * i <= n simuleaza conditia i <= sqrt(n) fara a lucra cu numere reale
    if (n % i == 0) {
          printf("%d", i);             // afiseaza pe ecran toate numerele impare de la 3 la sqrt(n)
                                       // care sunt divizori ai lui n
    }
}
 
... 
for (int i = 0; i < n; ++i) {
    for (int j = 0; j < n; ++j) {
         printf("%d ", j);
    }
    printf("\n");
}

Observațiile de mai sus sunt valabile și pentru celelalte cicluri repetitive.

Analizați exemplele de funcții de mai jos și observați că.

• numele funcțiilor e sugestiv
• spațierea se menține și la nivelul listei de parametri
  • ATENȚIE! Nu punem spațiu între numele funcției și '('
  • Asemănător cu instrucțiunile, lăsăm un spațiu între ')' și '{'
  • Lăsăm un spațiu mereu după virgulă, niciodată înainte de virgulă.

void clean_display() {
    ...
}
 
 
...
 
void print_array(int n, int v[NMAX]) {
    ...
}
 
int print_gigel(int gigel) {
    ...
    return result;
}
 
int count_duplicates(int n, int v[NMAX]) {
    int x = n;             // niciodata nu lasam prima linie dintr-un block {} goala, nu are sens
    ...
                           // daca avem mai multe declaratii/alocari etc putem lasa o linie goala sa aratam ca ca s-a terminat initializarea
    int cnt = 0;
    for (int i = 0; i <= n; ++i) {
        ...
    }
                          // mai las o linie goala (optional) sa arat ca s-a terminat algoritmul 
    print_gigel(cnt);    
    return cnt;
}

Fie următorul șablon de program. Analizați: * cum scriem în fișier mai multe funcții * care e structura generală a unui program

#include <stdio.h>
...                 // alte biblioteci incluse sau macro-uri
#include <math.h>
#define NMAX 100    // nu vom declara tablouri cu int v[100]; ci vom folosi un macro pentru dimensiune      
                    // linie goala
void dummy() {
}
                    // lasam o linie goala intre functii
int print_array(int n, int v[NMAX]) {
     ...
}
                    // lasam o linie goala intre functii
int main() {
   ...
   return 0;
}

Evident ca atunci cand fișirul main devine prea mare, este nevoie să grupăm componentele după logică și să le mutăm în alte fișiere sursă C/headere.

Toate aspectele menționate mai sus sunt foarte importante și trebuie să vi le însușiți. Evident că la început este greu să rețineți toate regulile, de aceea va punem la dispoție o modalitate de testare, folosind scriptul Google C++, adaptat pentru nevoile noastre.

Varianta de script pe care o vom folosi la PC este aici.

Să presupunem că cineva a scris din greșeală următorul cod (sigur nu voi).

#include <stdio.h>
 
int main()
 
 
{
 
int x = 0;
    printf("%d\n"
 
 
    	, x);
 
    return 0;}

În caz că nu observ problemele pe care trebuie să le corectez, rulez următoarea comandă:

darius@pc ~ $ python cs.py cs_negative_example.c
cs_negative_example.c:0:  No copyright message found.  You should have a line: "Copyright [year] <Copyright Owner>"  [legal/copyright] [5]
cs_negative_example.c:6:  { should almost always be at the end of the previous line  [whitespace/braces] [4]
cs_negative_example.c:7:  Redundant blank line at the start of a code block should be deleted.  [whitespace/blank_line] [2]
cs_negative_example.c:12:  Tab found; better to use spaces  [whitespace/tab] [1]
Done processing cs_negative_example.c
Total errors found: 4

Dacă vom corecta cele reclamate de script, vom obține un nou fișier cu următorul conținut:

// Copyright 2018 Darius Neatu (neatudarius@gmail.com)
 
#include <stdio.h>
 
int main() {
    int x = 0;
    printf("%d\n", x);
    return 0;
}

Rulăm din nou scriptul și observăm că problemele au dispărut.

darius@pc ~ $ python cs.py cs_positive_example.c 
Done processing cs_positive_example.c
Total errors found: 0

Este foarte important să avem un coding style OK. Această pagină vine în ajutorul vostru.