feat(Car.java): ajout commentaires et amelioration

src/Car.java

@@ -2,57 +2,73 @@ import java.awt.Color;
 import java.util.Random;
 
 /**
- * <code>Car</code> représente une voiture qui avance sur un circuit en boucles.
- * Chaque appel à {@link #makeMove()} avance la voiture d'une position.
+ * {@link Car} représente une voiture qui avance sur un circuit en boucles.
+ * Chaque appel à {@link #run()} avance la voiture d'une certaine position et fait perdre de l'essence.
  * Quand la position atteint la fin de la boucle, un nouveau tour est compté.
+ * <p>
+ * La voiture consomme du carburant à chaque déplacement, et son score
+ * est calculé en fonction du nombre de tours complétés et de sa progression sur le tour actuel.
+ * </p>
  */
 public class Car
 {
-    /** Ajout de la classe Random (Evite de le recreer a chaque fois) */
-    private Random rand = new Random();
+    /** Générateur de nombres aléatoires pour simuler la progression */
+    private final Random rand = new Random();
 
-    /** Couleur de la voiture */
+    /** Couleur de la voiture pour l'affichage */
     private Color color;
     /** Nom de la voiture */
-    private String name;
+    private final String name;
+
+    /** Position actuelle dans la boucle (entre 0 et loop) */
+    private int pos = 0;
 
-    /** Position actuelle dans la boucle (entre 0 et loop inclus) */
-    private int pos		= 0;
-    
     /** Nombre de tours complétés */
-    private int round 	= 0;
-    
-    /** Nombre total de cases dans une boucle (doit être > 0) */
+    private int round = 0;
+
+    /** Nombre de cases dans une boucle (doit être > 0) */
     private final int loop;
+
+    /** Référence à l'état du jeu, pour récupérer les paramètres comme la consommation */
     private final State state;
-    /** Nombre de fuel restant */
-    private int fuel    = 60;
+
+    /** Carburant restant */
+    private int fuel = 60;
 
     /**
      * Construit une nouvelle voiture.
      *
+     * @param name nom de la voiture
+     * @param color couleur de la voiture
      * @param loop nombre de positions par boucle (doit être > 0)
-     * @throws IllegalArgumentException si {@code loop <= 0}
+     * @param state état global du jeu
      */
     public Car(String name, Color color, int loop, State state)
-	{
-        this.name = name;
-        this.color = color;
-        this.state = state;
-
+    {
         if (loop <= 0)
-            throw new IllegalArgumentException("loop must be > 0!");
-        this.loop = loop;
+        {
+            System.err.println("le tour de la piste doit etre positif");
+            System.exit(1);
+        }
+
+        this.name  = name;
+        this.color = color;
+        this.loop  = loop;
+        this.state = state;
     }
 
     /**
-     * Fait avancer la voiture d'une position.
-     * <p>Si la position atteint la fin de la boucle, un nouveau tour est compté.</p>
+     * Fait avancer la voiture d'un certain nombre de positions.
+     * <p>
+     * Si la position atteint la fin de la boucle, le compteur de tours est incrémenté et
+     * la position revient à zéro.
+     * </p>
      *
+     * @param move nombre de positions à avancer
      * @return cette même instance (pour chaînage fluide)
      */
     public Car makeMove(int move)
-	{
+    {
         pos += move;
         if (pos >= loop)
         {
@@ -66,15 +82,16 @@ public class Car
      * @return la position actuelle dans la boucle
      */
     public int getPosition()
-	{
+    {
         return pos;
     }
 
     /**
-     * @return le score, calculé comme (nombre de tours + progression du tour) × 100
+     * @return le score de la voiture, calculé comme :
+     *         (nombre de tours + progression du tour) × 100
      */
     public int getScore()
-	{
+    {
         return (int) ((round + (float) pos / loop) * 100);
     }
 
@@ -82,57 +99,91 @@ public class Car
      * @return le nombre de tours complétés
      */
     public int getRound()
-	{
+    {
         return round;
     }
 
     /**
-     * @return la taille de la boucle (nombre de positions)
+     * @return le nombre total de positions dans la boucle
      */
     public int getLoop()
-	{
+    {
         return loop;
     }
 
+    /**
+     * @return le carburant restant
+     */
     public int getFuel()
     {
         return fuel;
     }
 
-    public  Car consumeFuel()
+    /**
+     * Consomme du carburant en fonction de l'état du jeu.
+     *
+     * @return cette même instance pour chaînage
+     */
+    public Car consumeFuel()
     {
         fuel -= state.getConsumption();
+        if (fuel < 0) fuel = 0; // sécurité
         return this;
     }
 
+    /**
+     * Exécute une "étape" de la voiture : avance d'une position aléatoire et consomme du carburant.
+     * <p>
+     * La progression est déterminée par un intervalle aléatoire fourni par l'état du jeu.
+     * </p>
+     */
     public void run()
     {
-        if (this.fuel > 0)
+        if (fuel > 0)
         {
             int[] interval = state.getInterval();
+            // avance aléatoire en fonction de l'interval
             int random = rand.nextInt(interval[0], interval[1]);
-            makeMove(random).consumeFuel();
+            
+            makeMove(random);
+            consumeFuel();
         }
     }
 
+    /**
+     * @return la position actuelle (synonyme de getPosition)
+     */
     public int getPos()
     {
         return pos;
     }
 
+    /**
+     * @return la couleur de la voiture
+     */
     public Color getColor()
     {
         return color;
     }
 
+    /**
+     * Définit la couleur de la voiture
+     *
+     * @param color nouvelle couleur
+     */
     public void setColor(Color color)
     {
         this.color = color;
     }
 
+    /**
+     * Représentation textuelle de la voiture (son nom)
+     *
+     * @return nom de la voiture
+     */
     @Override
     public String toString()
     {
-        return this.name;    
+        return this.name;
     }
 }