TP 0

Ce document fournit le contexte et les instructions de remise pour le « Travail Pratique 0 » (TP 0).

Contexte

Ce TP sert de point d’entrée pour votre future implémentation de Skyjo. Comme Skyjo est un jeu de cartes, vous commencerez par une implémentation solide des cartes de base, afin que les prochains TP disposent d’une base fiable sur laquelle construire.

Le TP sert également de premier point de contrôle pour la gestion des interfaces Java et la définition de classes personnalisées implémentant une interface fournie (voir atelier 02).

Réussir le TP0

Le TP0 est tout à fait réalisable et ne nécessite pas de compétences avancées en programmation. Cependant, il est essentiel de lire attentivement et de suivre les instructions, et de résoudre les tâches par vous-même.

Objectifs d’apprentissage

Dans ce TP, vous allez :

Rafraîchir des concepts de programmation de base.
Acquérir de l’expérience dans la lecture de documentation logicielle.
Pratiquer quelques concepts avancés de programmation orientée objet, présentés en classe, et qui constituent la base de votre implémentation de Skyjo.
Pratiquer une soumission simple de fichiers sur GitLab.
Obtenir une première expérience avec les retours automatisés et apprendre à interpréter les résultats.

Il ne s’agit pas d’un TP de programmation : l’intérêt porte moins sur le code relativement simple à développer que sur les outils et les pratiques mis en jeu.

Travail individuel

Contrairement à tous les TP ultérieurs, le TP0 est un travail individuel. Afin d’assurer l’atteinte de vos objectifs d’apprentissage, vous êtes tenu de ne pas copier le travail de vos camarades.
L’utilisation de l’IA générative compromet également vos objectifs d’apprentissage. Toutes les informations nécessaires se trouvent dans le matériel du cours.

Votre formation == votre responsabilité

Une réalisation individuelle et sérieuse des TP fait partie de votre préparation aux examens. Le sérieux que vous accordez à votre formation est une décision personnelle ; personne ne contrôlera ni n’imposera votre façon d’aborder les TP.

Remise

Nous utilisons un système de rétroaction automatisée ; il est donc crucial de suivre exactement les instructions de téléversement. Votre soumission ne sera pas considérée si :

Elle est remise après la date limite (ne me contactez pas pour une prolongation).
Elle est remise ailleurs qu’à l’endroit demandé. Votre code doit…
- se trouver dans un projet GitLab public et vous devez en être le créateur (voir les instructions plus bas) ;
- respecter la structure de projet demandée ;
- respecter les noms de fichiers demandés.

Vérifiez votre remise

Vérifiez votre remise ; je rejette catégoriquement toute soumission faite ailleurs ou ne respectant pas les conventions.

Date limite

Le TP0 est à remettre dimanche 25 janvier à 23 h 59.

Code

Vous devrez travailler avec du code fourni et respecter la structure de projet demandée.

Vous pouvez copier-coller le code fourni à partir de cette page web.
De plus, vous pouvez vous familiariser avec les deux classes fournies en consultant la page JavaDoc associée.

Pourquoi ne puis-je pas simplement coder à ma façon, à partir de zéro ?

Une partie du jeu que vous allez développer sera fournie, notamment l’interface utilisateur textuelle. Les parties existantes et votre solution doivent fonctionner ensemble de façon cohérente. Il est donc crucial de respecter rigoureusement les interfaces fournies.

Classes et structure

Avant de travailler sur le code proprement dit, commençons par créer un nouvel espace de projet :

Créez un nouveau dossier nommé TP0 (assurez-vous qu’il soit en majuscules).
À l’intérieur du projet, créez un nouveau dossier src.
Dans le dossier src, créez quatre nouveaux fichiers Java, comme de simples fichiers texte. Utilisez exactement les noms de fichiers tels qu’indiqués ci-dessous et utilisez exactement le code listé ci-dessous.

Par la suite, vous devriez voir cette structure (et rien d’autre !) :

TP0
└── src
    ├── Main.java
    ├── CardType.java
    ├── CardImpl.java
    └── Card.java

Code de lancement (fourni)

Fichier Main.java
Cette classe sert de point d’entrée pour votre TP0, afin que vous puissiez exécuter votre code. Elle crée simplement deux nouveaux objets CardImpl et vérifie si leurs propriétés s’affichent correctement à l’écran.
Cette classe, à elle seule, n’est pas fonctionnelle ; il est donc tout à fait normal de voir apparaître certains avertissements / erreurs une fois que vous aurez ajouté cette première classe.

public class Main {

  /**
   * Launcher for Skyjo TP0.
   * The code below is to illustrate how CardImpl implementations are used. Student code will be
   * tested BEYOND the examples below.
   *
   * @param args none.
   */
  public static void main(String[] args) {

    // Example 1, card "-1"
    Card testCardMinus1 = new CardImpl(-1);
    System.out.println(testCardMinus1.getType());
    System.out.println(testCardMinus1);
    // Must print:
    //    NUMERIC_NEGATIVE
    //    -1

    // Example 2, card "12"
    Card testCard12 = new CardImpl(12);
    System.out.println(testCard12.getType());
    System.out.println(testCard12);
    // Must print:
    //    NUMERIC_POSITIVE_HEAVY
    //    12
  }
}

Enum des types de cartes (fourni)

Fichier CardType.java
Cette classe est une énumération (Enum). Vous avez certainement déjà travaillé avec des énumérations dans votre cours d’introduction à la programmation, mais pour rappel : les énumérations sont des objets qui ne peuvent prendre qu’un ensemble précis de valeurs. Dans le contexte de Skyjo, nous les utilisons pour distinguer différentes catégories de cartes (cela deviendra plus important par la suite, lorsque nous aborderons l’affichage en couleur — différentes valeurs de l’énumération sont associées à différentes couleurs).

/**
 * Enum for various types appearing in Skyjo (action).
 *
 * @author Maximilian Schiedermeier
 */
public enum CardType {

  /**
   * Represents cards with value below 0.
   */
  NUMERIC_NEGATIVE,

  /**
   * Represents cards with value equal 0.
   */
  NUMERIC_NEUTRAL,

  /**
   * Represents cards with mildly positive value, i.e. 1-4.
   */
  NUMERIC_POSITIVE_LIGHT,

  /**
   * Represents cards with moderately positive value, i.e. 5-8.
   */
  NUMERIC_POSITIVE_MODERATE,

  /**
   * Represents cards with heavily positive value, i.e. 9-12.
   */
  NUMERIC_POSITIVE_HEAVY,

  /**
   * Represents special cards.
   */
  SPECIAL
}

Pourquoi existe-t-il une catégorie SPECIAL ?

Skyjo possède plusieurs variantes de jeu. La variante vue en classe ne comporte que des cartes numériques, et vous ne construirez que cette variante de base. Toutefois, afin de conserver une compatibilité ascendante, nous définissons tout de même une catégorie SPECIAL ici, afin de garder une option pour de futures extensions du jeu.

Interface de carte (fournie)

Fichier Card.java
Maintenant, on entre dans le vif du sujet ! Cette classe est une interface, ce qui signifie qu’elle ne fournit aucune fonctionnalité par elle-même. Elle sert de contrat pour spécifier précisément ce qui doit être implémenté par les sous-classes. Lisez attentivement l’interface, car elle vous indique exactement quelles exigences doivent être respectées par votre solution.

/**
 * Represents a Skyjo card. There a various types of cards, concerning values they represent and
 * their characteristic visualization. Cards must display neatly formatted when toString is
 * invoked, that is take up strictly two characters. Examples: "-2", " 2" (leading space), "12".
 * Cards have a type associated, based on their value. The ranges are: below 0: NUMERIC_NEGATIVE,
 * ==0: NUMERIC_NEUTRAL, 1-4: NUMERIC_POSITIVE_LIGHT, 5-8: NUMERIC_POSITIVE_MODERATE, 9-12:
 * NUMERIC_POSITIVE_HEAVY.
 *
 * @author Maximilian Schiedermeier
 */
public interface Card {

  /**
   * Getter for retrieving the type of given card object.
   *
   * @return CardType enum instance specifying the type.
   */
  CardType getType();

  /**
   * Getter for retrieving the numeric value, associated with the card object.
   *
   * @return value in range -2 to 12, associated with card object.
   */
  int getValue();

  /**
   * Getter for string version of card. Must print the card's value as two-character string. For
   * example: "-2", " 2" (mind the leading space character!), "12".
   */
  String toString();
}

Classe d’implémentation de carte (incomplète)

Fichier CardImpl.java
Et finalement, une classe incomplète. Elle est incomplète parce que, pour ce TP0, vous devez fournir les parties manquantes.
Remarquez la signature de classe implements Card ? Cela signifie que la classe ne compilera pas tant qu’elle ne satisfait pas les signatures de méthodes déclarées dans l’interface Card. (Si vous ne savez pas quoi faire, revenez à atelier02, où vous avez déjà pratiqué les interfaces et la façon d’implémenter les classes correspondantes.)

/**
 * This class implements the Card interface, and provides a correct
 * implementation of all required methods (including the toString method).
 */
public class CardImpl implements Card {

  // TODO: implement...
}

Lisez attentivement la documentation afin de vous assurer que votre implémentation fonctionne exactement comme prévu.

Anticiper les cas limites

Votre code sera testé au-delà de la classe de lancement fournie. Anticipez les scénarios d’erreur lors de l’implémentation de votre code afin d’augmenter votre note.

Récapitulatif

En résumé, du point de vue du code, vous devez uniquement :

Ajouter les quatre classes fournies à votre base de code (en respectant la structure de projet demandée !)
Implémenter votre classe CardImpl, sans modifier l’interface (les ingénieurs fournissent des solutions (implémentations) à des problèmes (interfaces), et non l’inverse !)
Et finalement, vous devez vous assurer que :
- Votre code compile.
- Le comportement de votre code est correct (il fait exactement ce qui est spécifié dans l’interface).
- Votre code est robuste (par exemple, une tentative de création d’une carte avec une valeur illégale -42 doit échouer. Vous pouvez simplement throw new RuntimeException dans ce cas).

GitLab

Dans ce cours, nous nous intéressons moins au code lui-même qu aux écosystèmes qui l’entourent.

Dans le cadre de ce TP0, vous aurez un premier contact avec un site web appelé GitLab.
Plus précisément, vous devez remettre votre code en utilisant GitLab. Assurez-vous d’utiliser le serveur GitLab du département d’informatique, et non un autre serveur GitLab. Le bon serveur est celui-ci : https://gitlab.info.uqam.ca

Avant de continuer, veuillez vérifier que la commande git est bien installée, comme demandé lors du premier cours. Sinon, retournez à la page d’accueil et installez git maintenant.

Allez-y doucement

Git est un outil puissant, et vous allez travailler intensivement avec git au cours des prochains mois. Il est aussi complexe ; au début, certaines choses peuvent donc sembler un peu cryptiques. À ce stade, il n’est pas nécessaire de comprendre toutes les commandes ; il suffit de comprendre que vous les utilisez pour téléverser (push) votre code vers un serveur.

Création d’un projet GitLab

Voici ce que vous devez faire, étape par étape :

Ouvrez votre navigateur et visitez : https://gitlab.info.uqam.ca/users/sign_in
Utilisez votre compte UQAM standard (votre code MS, c’est-à-dire le même que pour Moodle) pour vous connecter.
Cliquez sur le signe + en haut à gauche. Sélectionnez New project / repository.
Dans la boîte de dialogue du type de projet, sélectionnez Create blank project :
Remplissez le formulaire comme suit :
- Nom du projet : tp0 (en minuscules)
- URL du projet (menu déroulant) : sélectionnez votre nom (dernière option de la liste)
- Project slug : tp0 (en minuscules)
- Niveau de visibilité : public (si vous choisissez autre chose, je ne pourrai pas y accéder / le corriger)
- Configuration du projet : DÉCOCHEZ l’option « Initialize repository with a README ».
- VÉRIFIEZ À NOUVEAU tout ce qui précède. Seulement ensuite, cliquez sur « Create project ».
Vous verrez de nombreuses commandes d’exemple, que vous devez ignorer. Utilisez plutôt les commandes suivantes :
- Faites un cd dans votre dossier de projet, c’est-à-dire dans le dossier TP0 que vous avez créé plus tôt (qui contient directement votre code Java).
- Tapez : git init (si vous n’avez pas encore installé git, retournez au premier cours et suivez les instructions d’installation).
- Ensuite, utilisez ces commandes pour synchroniser votre code avec le serveur GitLab :
```
git add src
git commit -m "initial commit"
# Remplacez XXXXXX par votre nom d’utilisateur GitLab
git remote add origin git@gitlab.info.uqam.ca:XXXXXXX/tp0.git
git push --set-upstream origin main
```
- Actualisez la page du navigateur. Vous devriez maintenant voir le dépôt rempli avec vos quatre fichiers de code.
Si vous modifiez votre code et souhaitez téléverser une version plus récente, utilisez simplement ces commandes :
```
git add src
git commit -m "New code version"
git push
```

Encore une fois, ne vous inquiétez pas si cela vous semble un peu cryptique pour l’instant, nous couvrirons git de manière approfondie très bientôt.

Remise de votre code

Pour que je puisse accéder à votre code, vous devez ajouter une ligne à ce formulaire, pointant vers votre classe CardImpl.java. (Le reste ne m'intéresse pas, puisque je vous ai fourni le code restant) : Feuille de remise

Fournir le lien vers le code brut

Assurez-vous de fournir le lien vers votre code brut, c’est-à-dire uniquement le code et seulement pour le fichier CardImpl.java. Lorsque vous testez votre lien, vous devez voir seulement le code sans quelconque décoration.

Pour obtenir le code brut de votre fichier CardImpl.java :

Accédez à votre projet sur GitLab.
Cliquez sur la classe CardImpl.java.
Cliquez sur le bouton 'open raw' en haut à droite de votre extrait :
Vous verrez le code sans décoration. Copiez l’URL depuis la barre d’adresse de votre navigateur et collez-la dans la colonne B de la feuille Excel de remise, juste à côté de votre code permanent.
Si vous voyez un symbole d’avertissement, cela signifie que votre lien ne pointe pas vers GitLab, ou qu’il ne s’agit pas d’un lien vers le code raw.

Soyez respectueux

Bien sûr, il serait possible de saboter la remise d’un autre étudiant en modifiant son URL. Ne le faites pas — Excel conserve un historique, donc nous saurons qui est le coupable.
Malheureusement, je dois inclure cet avertissement pour une raison.

Évaluation

Votre remise sera évaluée automatiquement
Vous recevrez un courriel quelques jours après la date limite.
Il s’agit d’une note virtuelle, uniquement pour votre considération :
- Elle ne compte pas pour votre note finale.
- Il est inutile d’essayer de négocier votre note.

Évaluation

Élément	Points
Lien vers le code brut `TrianglePrinterImpl.java` fourni.	10%
Le programme compile avec le fichier fourni, en utilisant JDK23.	10%
Le dépôt est exempt de fichiers superflus (fichiers non pertinents, ex. `.class`).	10%
Le programme gère correctement les entrées absurdes.	15%
Le programme associe correctement les cardTypes aux cartes.	25%
Le programme affiche correctement les cartes.	30%

Remarque : si le lien de téléversement ne fonctionne pas, vous recevrez 0. Si le programme ne compile pas, vous recevrez 0.

Qu’est-ce que les fichiers superflus

Les fichiers superflus sont des fichiers ou dossiers dans votre dépôt qui sont non pertinents et non demandés. Pour le TP0, votre dépôt ne devrait contenir que le dossier src et 4 fichiers Java : tout le reste présent dans votre dépôt est considéré comme superflu (.class, dossiers additionnels, fichiers IDE, binaires, ...)

Vous pouvez supprimer les fichiers superflus avec la commande git rm :

git rm fichierSuperflu
git commit -m "fichiers superflus supprimés"
git push

Divers

Autres mentions concernant le TP0 :

Recommandations

Commencez tôt, GitLab est un serveur et le téléversement peut échouer.
Respectez la version de JDK demandée. Votre programme pourrait ne pas compiler si vous utilisez autre chose que JDK23.
Évitez les IA génératives. La tâche est très simple, tout ce dont vous avez besoin est fourni dans le matériel du cours. Utiliser ChatGPT ou similaire compromet votre préparation à l’examen et mènera presque certainement à une note finale plus basse.

Questions

Il est normal d’avoir des questions, et je vous encourage à bien comprendre le TP0 avant de vous investir.
Toutefois, ne m’envoyez pas de courriel.
Posez plutôt vos questions en classe et sur Mattermost.
N’hésitez pas également à répondre aux questions ouvertes de vos camarades.