<div class="page"> <div class="cover text-center"> <img class="mx-auto" src=/itb/images/logo_mislata.png alt="logo"> # Documentació Xarxa Social <div class="text-end fit-content ms-auto my-3 mt-auto pt-3"> <p><strong>Autor:</strong> Joan Puigcerver Ibáñez</p> <p><strong>Correu electrònic:</strong> j.puigcerveribanez@edu.gva.es</p> <p><strong>Curs:</strong> 2024/2025</p> </div> <div> <p class="fw-bold mb-0">Llicència: BY-NC-SA</p> <p class="d-none d-md-block">(Reconeixement - No Comercial - Compartir Igual)</p> <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/deed.ca" target="_blank"> <img class="mx-auto" src="/itb/images/license.png" alt="Licence"/> </a> </div><!--license--> </div><!--cover--> </div><!--page--> {:toc} ## Solució Podeu consultar la solució a: - Codi font: https://github.com/fpmislata-dam1s-ed/PuigcerverJoan-ED-solucions/tree/main/src/main/java/ud6/practices - Documentació generada i publicada: https://fpmislata-dam1s-ed.github.io/PuigcerverJoan-ED-solucions/ud6/practices/package-summary.html ## Errors més comuns Vos deixe un resum amb els errors més comuns que he trobat en les vostres pràctiques: ### Descripció de les classes La descripció de les classes ha d'indicar quin és el propòsit o què representa. ::: example La següent descripció de la classe `Post` no és una bona descripció per diferents motius: - Ja és veu que és una classe. No cal indicar-ho. - No s'explica què representa la classe. - Indica aspectes tècnics de la implementació que no són rellevants per a l'usuari de la classe. ```java /** * Clase Post, post de los usuarios en los que se puede * dejar comentarios, ya que, implementa la clase Commentable */ class Post implements Commentable { // ... } ``` La descripció podria ser alguna cosa semblant a: ```java /** * Representa una publicació en la xarxa social. */ class Post implements Commentable { // ... } ``` En aquest cas: - És una descripció més clara i concisa. - Indica què representa la classe. - No entra en detalls tècnics de la implementació. ::: ### Tipus en els atributs No cal indicar el tipus en la descripció dels atributs. ::: example La següent descripció de l'atribut `content` no és una bona descripció perquè indica el tipus de l'atribut. - A la definició ja s'indica el tipus de dades de l'atribut. ```java /** * String amb el contingut de la publicació. */ private String content; ``` La descripció podria ser alguna cosa semblant a: ```java /** * Contingut de la publicació. */ private String content; ``` ::: ### Nom de l'element innecessari No cal indicar el nom de l'element (classe, mètode, constructor...) a la descripció. Tampoc cal indicar que signifiquen les etiquetes `@return`, `@param`, etc. ::: example Les següents descripcions no són del tot correctes perquè indicen el nom de l'element, que ja es veu a la definició d'aquest. ```java /** * Classe Post que representa una publicació en la xarxa social. */ public class Post { /** * Atribut content que conté el contingut de la publicació. */ private String content; /** * Constructor de la classe Post. */ public Post() { // ... } /** * Mètode getter que retorna el contingut de la publicació. * @return Retorna el contingut de la publicació. */ public String getContent() { return content; } } ``` Les descripcions podrien ser alguna cosa semblant a: ```java /** * Representa una publicació en la xarxa social. */ public class Post { /** * Contingut de la publicació. */ private String content; /** * Crea una nova publicació. */ public Post() { // ... } /** * Obté el contingut de la publicació. * @return Contingut de la publicació */ public String getContent() { return content; } } ``` ::: ## Conclusió Una documentació clara i concisa és molt més útil que una documentació llarga amb massa detalls tècnics. - La documentació ha de ser fàcil de llegir i d'entendre. - Ha de proporcionar la informació bàsica i necessària per entendre el funcionament de les classes, mètodes, etc.