În prima secțiune vom discuta despre comentariile din codul sursa si cum se documenteaza un API. In a doua parte vom vorbi de Continuous Integration, in ce consta si moduri de a analiza codul.

Comentariile sunt printre cele mai folosite si abuzate moduri de a documenta codul. Acestea pot fi folosite pentru a ascunde diverse imperfectiuni ale codul sau proiectului ca nume neinspirate ale variabilelor sau functiilor, design slab al codului sau lipsa uneltelor de proces (sistem de versionare, issue tracking etc.). Comentariile pot fi utile pentru a explica de ce este facut un lucru in cod, pentru a documenta un design bazat pe pseudo-cod sau pentru a referentia lucruri conexe.

• Repetare a codului
  • Inutile
• Explicarea codului
  • Utile in cazul in care codul nu este clar, dar in acest caz prioritatea ar fi clarificarea codului
• Markers
  • Note menite sa fie scoase din codul final
  • Utile daca sunt standardizate ex. // TODO
• Rezumat al codului
  • Aplicate pentru sectiuni mai mari de cod
  • Utile pentru a intelege mai repede si usor codul
• Descriere a unei potentiale probleme
  • Asemanator cu rezumatul, doar ca se descrie o potentiala problema
• Alte informatii care nu pot fi exprimate in cod
  • Numele autorilor, copyright, data modificarii etc.

Uneltele de documentare a API-urilor au devenit extrem de comune in prezent. Acestea:

• Reflecta accentul modern pus pe interfetele reutilizabile
• Combina informatii de la
  • Un parser limitat de limbaj (pentru a extrage informatii despre structura modulului/functiei si parametrii asociati
  • Sectiuni de comentarii special formatate din codul sursa
• Incurajeaza actualizarea comentariilor pe masura ce codul este modificat

Una dintre cele mai cunoscute unelte de documentare a API-urilor pentru ca este inclusa in distributia standard de Java. Comentariile specifice JavaDoc:

• Sunt delimitate de /** … */, implicit procesate ca si comentarii de compilator
• Preced sectiunea de cod pe care o comenteaza
• Pe langa orice text, acestea pot contine marcaje speciale cum ar fi @author <authorName>, @param <name> <description>, @return <description> etc.

Pentru a genera documentatia folosind JavaDoc se poate folosi:

• Linia de comanda javadoc -d destinationDir -sourcepath sourceCodeDir \ -link http://docs.oracle.com/javase/7/docs/api/
• IntelliJ: Tools→Generate JavaDoc
• Alte IDE-uri de Java ex. Eclipse

Exemplu de clasa Java documentata:

import java.io.*;
 
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }
 
   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */
 
   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);
 
      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

Pe langa verificarea functionalitatii codului prin testare, un alt mod de a cuantifica calitatea/performanta acestuia este prin a utiliza unelte de analiza. Aceste unelte pot face:

• Analiza statica
  • Fara a rula codul
  • Verifica coding style-ul folosit
  • Verifica data flow-ul programului prin reprezentarea programului ca un graf
• Analiza dinamica
  • Ruleaza codul
  • Urmareste utilizarea memoriei pentru a detecta memory leaks sau alte probleme
  • Masoara performanta prin profiling

In cadrul Continuous integration practicile de version control, compilarea si testarea automata sunt combinate astfel incat schimbarile care ajung in repository-ul de version control sunt automat rebuild-ate, testate si regenerate rapoartele aferente. Este de preferat sa se faca aceste lucruri complet sau partial pentru a reduce riscul ca schimbarile noi sa introduca probleme ca erori de compilare sau bug-uri.
Pentru ca sunt multi pasi necesari in a executa un plan de Continuous Integration, durata poate sa fie extrem de mare. Datorita acestui fapt, de fiecare data cand se introduc schimbari noi se va prefera rularea unui plan redus(de exemplu care include compilarea si analiza statica, dar nu include testare si analiza dinamica). Planul complet poate sa fie rulat ocazional, cum ar fi peste noapte, cand poate sa dureze mult mai mult. Pentru a putea beneficia de Continuous Integration, un proiect trebuie sa aiba mai multe caracteristici:

• Sistem de control al versiuni cu branch principal clar identificat sau set de branch-uri de development
• Build automat
• Dezvoltatori care introduc schimbari frecvent (poate de mai multe ori pe zi)
  • Commit-uri introduse pe branch-uri urmarite (ex. cu pull-request asociat) sunt verificate cu un plan minimal de Continuous Integration (compiling, static analysis)
• Testarea se face, ideal, pe o clona a mediului de productie
  • Diferit de mediul de dezvoltare
  • De obicei verificat rar
  • Poate sa foloseasca mai multe masini de rulare pentru a putea viza sisteme cu configuratii diferite sau pentru a paraleliza volumul de munca

Avantaje:

• Problemele de integrare sunt identificate si rezolvate repede
• Schimbarile sunt testate cat mai repede posibil
• Se pune accentul pe check-in-uri frecvente, astfel se incurajeaza modularitatea

Dezavantaje:

• Efort initial ridicat pentru a face setup la sistem
• In functie de structura proiectului, e necesar un anumit nivel de rafinament pentru a pune fiecare pas de verificare intr-un build automat

Un server de Continuous Integration este o masina accesibila din retea care:

• Are accesul la informatiile legate de proiectele care trebui rulate, locatia si informatiile de acces la repository-ul de version control, ce branch-uri sa urmareasca, cum sa faca build la proiect si ce rapoarte trebuie sa produca
• Monitorizeaza repository-ul de version control pentru a vedea noi commit-uri
• Cand un push la un branch urmarit apare, server-ul de CI notifica un runner

Un CI runner (sau nod) e un proces pe o masina care:

• Are uneltele necesare pentru a face build la proiect
• Este gestionat de serverul de CI

Cand un runner este notificat de serverul de CI, acesta:

• Cloneaza branch-ul pe care se doreste rularea build-ului din repository-ul de version control
• Ruleaza build-ul
• Publica rapoartele rezultate build-ului
  • Poate publica si “artefacte”: fisiere generate care contin informatii aditionale cum ar fi versiunea uneltelor folosite in cadrul build-ului

GitHub furnizeaza o solutie integrata de Continuous Integration printr-un serviciu numit “Actions”.
Acest serviciu poate fi accesat din pagina proiectului, selectand tab-ul Actions, de exemplu.
Pentru a creea un Action nou, este necesara creearea unui fisier de workflow la calea .github/workflows/ din repository. Acest lucru se poate face atat local cat si din GitHub. Fisierul de workflow are extensia .yml pentru ca foloseste sintaxa YAML si contine indicatii legate de cand si ce este executat in cadrul unui action. Un exemplu de fisier de workflow care face build la un proiect Java cu Apache Ant gasiti aici.
Fisierele ce pot rezulta in urma rularii anumitor pasi pot fi publicate ca artefacte si in cadrul GitHub Actions. Pentru a face acest lucru, puteti folosi urmatoarea sintaxa, dupa pasul de generare al fisierului dorit:

- name: Upload a Build Artifact
    uses: actions/upload-artifact@v3.0.0
    with:
      # Artifact name
      name: # optional
      # Destination path
      path: # optional

1. Descarcati si importati in IntelliJ proiectul din arhiva lab8.zip.
2. Documentati API-ul clasei CircularLinkedList, inclusiv clasa in sine. Documentarea consta in adaugarea unei scurte descriere a ce face clasa/functia si a parametrilor aferenti.
3. Creati functia cu antetul public Node getNextNode(Node currentNode); in clasa CircularLinkedList. Aceasta va intoarce urmatorul nod din currentNode. Documentati aceasta functie.
4. Generati documentatia folosind JavaDoc.
5. Faceti push la schimbari in GitHub. Aveti grija sa includeti doar fisierele necesare.
6. In GitHub, creati un Action care compileaza si ruleaza proiectul. Acesta va trebui sa foloseasca versiunea 17 de Java din distributia “temurin”.
7. Extindeti actiunea pentru a publica executabilul proiectului (fisierul .jar) ca artefact.
8. Extindeti actiunea pentru a genera documentatia proiectului folosind JavaDoc si a publica directorul documentatiei generate ca artefact. Verificati ca documentatia generata este aceeasi cu cea generata local.

• https://www.cs.odu.edu/~zeil/cs350/latest/Public/docgen/index.html
• https://www.cs.odu.edu/~zeil/cs350/latest/Public/continuousInteg/index.html
• https://www.cs.odu.edu/~zeil/cs350/latest/Public/analysis/index.html
• https://github.com/eugenp/tutorials/blob/master/data-structures/src/main/java/com/baeldung/circularlinkedlist/
• https://ant.apache.org/manual/using.html
• https://ucsb-cs56-pconrad.github.io/topics/javadoc_publishing_to_github_pages_from_public_repo/
• https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-ant
• https://www.tutorialspoint.com/java/java_documentation.htm