Catégorisation de "bonnes pratiques (BPs) de codage" générales

_______________________________________________________________________________________________________________________________________

Please enable Javascript in your browser since this page requires it to work correctly.


Préambule.

Préambule. Dans tous les domaines de l'informatique ou la plupart de ses langages de codage (d'informations ou de programmes), il existe des centaines de BPs et des centaines de pages Web qui chacune recense une dizaine à une centaine de BPs pour ce domaine ou langage, sans organisation systématique pour comparer, regrouper, retrouver, généraliser ou aider à mémoriser ces BPs.
La base d'une telle organisation, i.e. une manière systématique (et donc passant à l'échelle) d'organiser des BPs, est de distinguer – et de catégoriser – les différentes dimensions sous-jacentes à ces BPs. Voici deux dimensions importantes qui ici suffiront pour catégoriser de manière systématique des BPs importantes généralisant celles relatives à l'usage de HTML et CSS (et Javascript) :

  1. les "critères de qualité" généraux (e.g. pour le codage ; cf. section 0.1.1) ;
  2. les objets logiciels généraux (pour le codage ; cf. section 0.1.2) auxquels s'appliquent les BPs :
    instruments/résultats/contenants de description et donc, plus précisément, objets abstraits/concrets
    lexicaux/structurels/sémantiques instruments/résultats d'une description pour son contenu et sa présentation. La distinction "abstrait/concret" ici utilisée est celle classique en théorie de l'analyse syntaxique : i) les "éléments abstraits" font références aux structures de données stockant les informations importantes indépendamment de leurs entrées/sorties (dans quel ordre, avec quels identifiants, ...), et ii) les "éléments concrets" font références aux détails lexicaux et syntaxiques d'entrée/sortie mais PAS à des détails de présentation (donc PAS à des notions de fontes, d'indentation, ...).

Ces dimensions sont complémentaires : chacune offre un moyen complémentaire d'indexer les BPs. La 1ère est utilisée directement en section 0.2 pour lister des BPs générales (et pour tout objet logiciel) relatives à quelques critères de qualité. Pour catégoriser en profondeur, il est plus pratique de suivre tout d'abord la catégorisation de la 2ème dimension (celle des objets) puis de mentionner les critères satisfaits par les BPs pour ces objets. Il est également pratique de regrouper dans une section séparée et à part entière les BPs à propos des objets "concrets ou de présentation" (de code – informations ou programme – ou de résultats d'exécution de ce code), d'où le plan ci-dessous pour ce document. Certains types d'objets de la section 0.1.2 ne sont pas repris dans ce plan car les BPs à propos d'objets de ces types se rapportent aussi à des objets d'autres types et sont présentées via ces derniers.
Enfin, ce document – qui se focalise sur de BPs générales – est spécialisé par deux documents qui reprennent le même plan :

Pour les étudiants du cours "Projet HTML", toutes les BPs listées dans ces documents sont à suivre.

Pour ces étudiants, l'expression "il vaut mieux" implique "il vous faut". En d'autres termes, pour ces étudiants, toutes les BPs sont des règles à suivre. Ces documents contiennent aussi quelques règles à suivre qui ne sont peut-être pas toujours des BPs : pour certaines personnes, ces règles sont des BPs, pour d'autres personnes, ces règles ne sont pas des BPs. Néanmoins, les étudiants du cours "Projet HTML" doivent les suivre. Dans ces documents, ces règles particulières sont explicitement distinguées des autres BPs.
En entreprise, les programmeurs doivent suivre les règles/spécifications du client, du chef de projet et du directeur technique de l'entreprise. Dans le cours "Projet HTML", les enseignants et les responsables de TD jouent le rôle du client, du chef de projet et du directeur technique : ils indiquent aux étudiants un ensemble de règles (BPs, ...) à suivre et vérifient leurs suivis. Il est en effet important pour les étudiants d'apprendre à suivre différentes règles

0. BPs générales et dimensions de catégorisation

0.1. Catégorisation de "critères de qualité", objets et aspects généraux pour des BPs sur le codage

0.1.1. Catégorisation de "critères de qualité" généraux (e.g., pour le code ou le codage)

La notation utilisée pour les catégorisations dans ce document – et, plus généralement, dans ce cours – est illustrée et expliquée via diverses traductions dans ce document sur la catégorisation de HTML par rapport à d'autres langages.

Quality = Quality_of_a_thing, //the thing can be anything: a code (element), the coding process itself, ... \. { //no exclusion: many subcriteria shared by the two direct subtypes (→ design/usage) (Quality_related_to_the_design_of_a_thing \. e{ //the distinction made by the next two direct subtypes is classic but, as noted in the // annotation below, is problematic, hence not deepened here (Functional_quality = Quality_about_the_designed_behaviour_of_a_thing ) (Non-functional_quality_about_the_design_of_a_thing = Quality_about_the_architectural-design_of_a_thing, annotation: "Structural-quality and its subcriteria are usually categorized as non-functional BUT most of these subcriteria can be (and often are) also categorized as functional; similarly, Usability and its subcriteria are usually categorized as functional BUT many of these subcriteria can also be categorized as non-functional; of course, different persons make such categorizations: a logical person does not categorize a same thing as both functional and non-functional since these types are exclusive BUT the fact that different persons can differ in this particular categorization shows that these types are not sufficiently well-defined; HENCE, Structural_quality, Usability and their subcriteria are NOT categorized WITHIN this distinction here", \. (Ethical_quality annotation: "Ethical_quality can be evaluated objectively whenever the used subcriteria and the information about the evaluated thing are precise enough. E.g., it is often easy to evaluate whether a licence is respected or not. Similarly, conflicting individual criteria are not a problem when an aggregation function over individual criteria is given.", \. (Ethical_quality_regarding_the_respect_of_laws_when_creating_this_thing \. Ethical_quality_regarding_the_absence_of_plagiarism_when_creating_this_thing Ethical_quality_regarding_the_respect_of_licenses_when_creating_this_thing ) ) (Beauty //categorized here since design-related and not-functional annotation: "since Beauty is a subjective criteria, it cannot be used as a way to evaluate a thing unless with respect to a 'particular set of objective criteria' given by a person (e.g., a person enjoying/buying the thing) or set of persons; e.g., facial symmetry could be used to evaluate the beauty of a face; for a code, beauty can be seen by many persons as the result of respecting a particular set of BPs aimed at Structural_quality; thus, unless the thing is custom made for a particular person who has explicitly specified objective criteria for beauty and their priority over other qualities, beauty has less priority than any design criteria and can be considered 'enabled' (or a consequence of) respecting design criteria" ) ) } (Structural_quality \. e{ (Dependability \. e{ (Dependability_and_not-Security \. Maintenability //measure: mean time/%/... between a failure and its repair (Reliability //measure: mean time/percentage/... between failures \. Safety //measure: mean time/%/... between catastophic failures (Robustness \. Fault-tolerancy) ) ) (Dependability_and_security \. (Availability //measure: mean time/%/... of correct work \. Temporal_accessibility ) //measure: mean time/%/... to most persons (Integrity := ^"absence of improper alterations", \. e{ Data_integrity //← Data_authenticity, ... Process_integrity //→ Process_agent_accountability, ... } ) ) } ) (Security_and_not-dependability \. Confidentiality ) //← Unlinkability, Anonymity, ... (Correctedness-or-completeness_wrt_specifications-or-the-represented-domain \. (Consistency \. (Uniformity \. Interoperability)) (Completeness-related_criteria \. (Accuracy = Validity Correctness, \. Relevancy Precision (Trustability \. Origin_verifiability) ) (Organisational_accessibility_related_criteria //for any Thing, even a Process \. (Modularity \. (Genericity \. Scalability Sharability)) Cohesiveness Understandability Testability (Non-redundancy \. Conciseness) ) (Software-or-device_accessibility_related_criteria //see Usability below // \. (Interoperability \. Sharability) //and many others ) (Versatility \. Configurability Flexibility) ) ) (Efficiency_related_quality \. Performance_efficiency Algorithmic_efficiency (End-user_efficiency_related_quality \. End-user_effort_related_accessibility //see below ) ) } ) ) (Quality_related_the_usage_of_a_thing \. Functional_quality //see the annotation of Non-functional_quality_about_the_design_of_a_thing, above (Usability \. (Accessibility_related_criteria \. //none of the next direct subtypes are exclusive (Software-or-device_accessibility_related_criteria \. Physical_accessibility Mobility (Interoperability \. Sharability) ) Organisational_accessibility_related_criteria //in Completeness-related_criteria above (Cognitive_accessibility \. (Cultural_accessibility = Universality) (Understandability \. Learnability Memorability) Attractivity ) //Attractivity is meaningless unless defined by specifications (W3C_accessibility = "What the W3C calls 'Accessibility': some criteria of Cognitive_accessibility and Physical_accessibility, often focused on disabilities, and some criteria of Software-or-device_accessibility (some also belong to what the W3C calls Mobility)" ) (End-user_effort_related_accessibility annotation: "Something that is accessible wrt. some criteria but at the cost of efforts from the end-user is problematic. E.g., it is a shame to ask the end-user to * write things whereas allowing copy-pasting these things could be allowed; * re-enter already entered things. Yet, software and Web sites often do those shameful things" ) (Financial_accessibility \. Cost) ) //Financial_accessibility and Attractivity can depend on how all the other criteria are ) ) // satisfied; hence, the priority between them and these other criteria must be specified }. // by the person enjoying/buying the thing if this thing is custom-made for this person

0.1.2. Objets généraux pour le codage : instruments/résultat/contenants

Description_instrument-or-result_or_container \. e{ (Description_instrument-or-result \. c{ //this set of direct subtypes is complete and its elements are not exclusive (Description_instrument //BPs in Section 2 except if for presentation \. e{ (Language \. e{ Natural_language //so far, all languages regularly spoken by people (Formal_language = Information_representation_language Coding_language, \. e{ (Formal_syntax //defined by a formal grammar \. Abstract_syntax Concrete_syntax ) Formal_language-model //associates a logically defined semantic } // to the abstract syntax Formal_language-model-plus-syntax //e.g. all programming laguages ) } ) (Identifier //"formal" means "(only) 1 meaning and an explicitly represented one \. e{ (Formal_identifier = ID) //"formal" → refers to only 1 thing (Informal_identifier = Name) } ) // "explicitly represented" → usable for automatic logical inferences } e{ Description_instrument_for_information (Description_instrument_for_interactions \. Description_instrument_for_presentation ) //BPs in Section 3 } ) (Description_result \. e{ //the next "abstract/concrete" distinction is from the syntactic parsing theory: // - "abstract elements" refer to data structures storing the important information // regardless of how it is inputed/outputed (which order, with wich IDs, ...) // - "concrete elements" refer to the input/output lexical and syntactic details // but NOT to presentation (hence NOT to the use of italics, indentation, ...) (Description_abstract-object //BPs in Section 1 except if for presentation \. e{ (Code_description_abstract-object \. Software_abstract-object Data_abstract-object ) (Code-result_description_abstract-object //→ result content / presentation \. p{ Code-result_abstract-object_not_for_presentation //→ content Code-result_abstract-object_for_presentation //BPs in Section 3 } ) } ) (Description_concrete-object //BPs in Section 3 \. p{ Description_concrete-object_for_presentation Description_concrete-object_not_for_presentation } ) } ) } p{ Semantic_object Structural_object Lexical_object } p{ Type Individual_information-object } ) (Description_container \. (File \. p{ Directory (Non-directory_file \. e{ Regular_file //the most common kind Link //there are other kinds, e.g. "socket", "pipe", block" and "character" } ) } ) ) }.

0.2. Exemples de BPs générales – et pour tout objet – relatives à certains critères de qualité

0.2.1. Exemples de BPs générales relatives au critère de complétude [completeness]

0.2.1.1. Plus de BPs (non conflictuelles) sont suivies, le mieux

E.g. :

0.2.1.2. Restreindre aussi peu que possible : laisser le plus de choix possibles à l'utilisateur final et aux développeurs qui vont reprendre le code

E.g. :

Note : dans le cours "Projet HTML", chaque étudiant n'a droit qu'à 1 seule image pour chacun des deux TDs pré-projet, et 1 seule image pour la totalité des TDs du projet lui-même. Il n'y a par contre aucune restriction sur l'usage de graphiques. Voici quelques raisons pour cette règle (qui n'est pas en soi une BP mais est liée à des BPs) :

0.2.1.3. Représenter+vérifier toute information de manière aussi complète, précise, formelle et structurée que possible

Rappel (cf. section 0.1.2) : un "objet formel" a une "signification (sémantique) unique" (qui peut être très général, parfois seulement connu par l'auteur de l'objet, mais il n'y a pas d'ambiguïté entre deux sens différents) → une phrase formelle utilise une syntaxe formelle et des identificateurs formels → cette phrase peut donc être interprétée et vérifiée automatiquement par des logiciels connaissant la syntaxe du langage utilisé.

E.g. :

0.2.2. Exemples de BPs générales relatives au critère d'efficacité

0.2.2.1. Ne s'occuper de la performance que si cela rapporte plus que cela ne nuit

C'est une évidence pour tous les critères mais cette BP est quand même intéressante pour des logiciels car i) s'occuper de la performance rapporte souvent moins que de s'occuper d'autres critères, et ii) beaucoup d'informaticiens (en particulier les débutants) s'occupent beaucoup trop de performance et au dépend d'autres critères. S'occuper de certaines performances informatiques, notamment des complexités algorithmiques [ computational complexity, Algorithmic_efficiency] en temps, mémoire ou autres ressources, a un bon retour sur investissement. Voici un exemple d'article listant des avantages et inconvénients pour d'autres types de performance.

0.2.2.2. Ne pas imposer d'efforts inutiles de la part de l'utilisateur

Beaucoup de logiciels actuels

Vu que ces efforts sont inutiles (ré-entrer des informations n'apporte rien aux utilisateurs) et sont facilement évitables par les concepteurs du logiciel, les imposer est un signe de problème chez ces derniers :

Le critère d'utilité des efforts est ici capital. E.g., il est bien-sûr légitime – et requis – pour un enseignant i) de demander à ses étudiants de faire les efforts requis pour leur apprentissage, et ii) de les évaluer sur cela. Par exemple, pour des étudiants d'université, il est légitime de les entraîner à acquérir un "esprit universitaire" (→ sérieux, autonomie, intégrité, etc.) et donc, e.g., préparer leurs TDs, lire les ressources pointées, rattraper ses lacunes en cas d'absence du niveau pré-requis, etc. Pour ce cours, cela inclut l'application des BPs listées.

0.2.3. Exemples de BPs générales relatives au critère d'éthique

0.2.3.1. Ne pas tricher (plagier, ...)

E.g., créer un code en plagiant à 100% fera que ce code (pas sa source) aura une valeur 0 pour son attribut "Ethical_quality_regarding_the_absence_of_plagiarism_when_creating_this_thing".
Dans le cadre d'un TD de ce cours, copier le code d'un fichier existant qui n'a pas été explicitement donné pour être suivi (e.g. un fichier d'un autre étudiant) fera aussi que vous aurez 0/20 pour ce TD.

0.2.3.2. Ne pas faciliter le non-suivi de BPs

Ne pas effectuer une "mauvaise pratique" est une BP. Permettre à d'autres étudiants de ne pas suivre des BPs est une mauvaise pratique (→ pénalisable) car cet acte incite ces étudiants à ne pas suivre ces BPs (→ complicité de ce non-suivi). Par ailleurs, cet acte est pénalisant pour l'apprentissage de ces autres étudiants. Des exemples d'un tel acte sont

1. BPs relatives aux objets abstraits "informationnels" (i.e., tous les objets abstraits sauf ceux pour des présentations)

Cette section est actuellement vide dans ce document qui se focalise sur des BPs générales mais elle sera spécialisée par la section 1 de chaque document plus spécialisé :

2. BPs relatives aux instruments de description

2.1. BPs à propos d'identifiants (d'objets de codage)

Coding_best-practice_about_an_identifier = Naming_convention, good_for: Usability, \. ne{ (Restricting_local_identifiers_to_use_only_particular_characters \. Restricting_variables/constants/functions_names_to_alphanumeric_characters_plus_underscore Restricting_description-identifiers_to_use_only_alphanumeric_characters_plus_underscore_-_@_/ Restricting_relative_file-names_to_use_only_alphanumeric_characters_plus_underscore_dot_-_@ ) Using_English_names_for/within_local_identifiers (Systematically_following_identifier-creation_rules \. Using_only_defined_abbreviations Using_identifiers_that_do_not_require_comments_to_further_explain_what_they_are_about Prefixing_identifier_by_a_reference_to_their_types Distinguishing_and_ordering-or-normalizing_the_parts_of_identifiers ) }.

2.1.1. Pour les noms d'identifiants locaux, n'utiliser que certains caractères, et l'anglais

Un "identifiant local" est un identificateur|identifiant autre qu'une adresse Web (URL) ou, plus généralement, un IRI (Internationalized Resource Identifier).

2.1.1.1. Pour les noms de variables/constantes/fonctions, n'utiliser que les caractères alphanumériques et '_', et l'anglais

La plupart des langages de programmation (et plus généralement, des langages formels) restreignent les identifiants de variables/constantes/fonctions à n'utiliser que des caractères alphanumériques (a-z, A-Z, 0-9) et des soulignés – et à ne pas commencer par un chiffre).

Ceci réduit le confort de lecture/écriture de noms lorsque d'autres langues que l'anglais sont utilisés, par exemple parce que les caractères accentués ne peuvent être utilisés. Ce n'est pas une mauvaise chose car, pour des raisons de (ré-)utilisabilité [Usability], il vaut mieux coder dans la langue véhiculaire mondiale actuelle qui est l'anglais. Pour un étudiant (à l'université) qui ne maîtriserait pas bien l'anglais, une objection peut être que l'étudiant pourrait mieux – ou du moins, plus facilement – apprendre à coder s'il n'avait pas aussi à se focaliser à écrire ses commentaires ou noms de variables en anglais. Toutefois, cette objection a divers contre-arguments. E.g. :

C'est pourquoi, qu'utiliser l'anglais "pour le codage dans un contexte d'apprentissage à l'université" soit ou ne soit pas une BP, c'est une règle pour le cours "Projet HTML".

Pour des raisons de généricité/ré-utilisabilité, un code doit pouvoir être facilement converti dans d'autres langages formels. Donc, même si un langage formel particulier offre plus de choix pour les caractères d'identifiants, il vaut mieux ne pas les utiliser.

2.1.1.2. Pour les identifiants dans des langages de description/présentation de données (e.g. HTML, CSS) ou de connaissances (e.g. FL, FE, UML), n'utiliser que les caractères alphanumériques, '_' et '-' (plus éventuellement '@' et '/'), et l'anglais

En HTML 5, les identifiants doivent commencer par une lettre ([A-Za-z]) et peuvent être suivis par des caractères alphanumériques, '_', '-', ':' et '.'. Il vaut mieux éviter ces deux derniers caractères car ce sont des caractères spéciaux en CSS et dans d'autres langages. Pour les raisons données dans la précédente sous-section, il vaut mieux aussi utiliser l'anglais.

2.1.1.3. Pour les noms (relatifs) de fichiers, n'utiliser que les caractères alphanumériques, '_' et '-' (plus éventuellement '@'), et l'anglais

Les noms de fichiers peuvent être des noms de commandes ou des paramètres de commandes. Même si en théorie la plupart des langages de scripts (e.g. scripts shell ou MS-DOS) permettent de gérer des noms de fichiers qui contiennent des espaces, des caractères de ponctuation (e.g. ';', ','), de quotation (e.g. '"' et '`'), de comparaison (e.g. '<' et '>'), de groupement (e.g. '(' et ']'), et autres caractères spéciaux (e.g. '|', '$', '\' et '&'), c'est compliqué et beaucoup de commandes classiques ne gèrent pas correctement les fichiers contenant de tels caractères spéciaux (e.g. des espaces). Pour des raisons d'utilisabilité [Usability], les noms de fichiers ne doivent donc utiliser que des caractères alphanumériques, '_' et '-' (plus éventuellement '@'), et l'anglais. Le séparateur '_' est à utiliser pour séparer deux groupes de (méta-)données à l'intérieur d'un nom, et '-' est à utiliser pour séparer des mots à l'intérieur d'un groupe. En effet : i) il est classique (en français, anglais, ...) de considérer que '-' est prioritaire sur '_' (comme l'opérateur de multiplication est prioritaire sur l'opérateur d'addition), et ii) '-' est reconnu comme un séparateur de mots (comme un espace) par tous les "analyseurs de noms" (e.g., ceux des moteurs de recherche tels Google), alors que '_' est moins reconnu en tant que tel, et l'usage du style InterCap/CamelCase encore moins reconnu. La section 2.1.2.5 liste des méta-données qu'il est souvent utile d'encoder dans le nom d'un fichier.

Autres règles à suivre pour les noms de fichiers :

2.1.2. Suivre systématiquement des règles de création d'identifiants

Pour des raison d'accessibilité cognitive [Cognitive_accessibility] et plus généralement d'utilisabilité [Usability], ce à quoi réfère un identifiant (et ses propriétés importantes comme son type principal) doit être compréhensible par tout lecteur ayant accès aux règles de création d'identifiants utilisées.

2.1.2.1. Ne pas utiliser d'abréviation non définies

Dans ce cours, les seules abréviations utilisables sont celles définies dans un des documents de ce cours (→ vous n'avez pas le droit de définir vos propres abréviations mais vous pouvez demander l'ajout d'abréviations).

2.1.2.2. Utiliser des identifiants suffisament longs et explicites pour ne pas nécessiter de commentaire expliquant ce à quoi ils réfèrent

Il ne faut pas obliger le lecteur à mémoriser ou accéder (dans le même fichier ou dans un autre) des commentaires pour comprendre ce à quoi réfère un identifiant. Depuis les années 1980 (environ), l'usage de longs identifiants (e.g. de 50 caractères) n'a plus de conséquence négative discernable d'un point de vue informatique (restriction de la mémoire, diminution de performance pour les langages interprétés ou via les accès réseau).

2.1.2.3. Préfixer un identifiant par une référence à son type

Dans les langages typés (→ la plupart des langages compilés), le type d'un identifiant est donné lorsque l'identifiant est déclaré, mais il ne faut pas obliger le lecteur à mémoriser ou accéder (dans le même fichier ou dans un autre) ce type (c'est long, le lecteur ne le fera pas et des erreurs/difficultés de compréhension s'ensuivront).

Dans les langages non typés (→ la plupart des langages interprétés), le type d'un identifiant peut être donné via un commentaire informel (→ ignoré par les logiciels), une annotation (un commentaire formel dont le contenu peut être interprété par des logiciels) ou une partie distincte dans le nom de l'identifiant (c'est la meilleure solution tant pour le lecteur humain que pour des explotations automatiques, e.g. des traductions entre des langages typés et des langages non typés).

Dans ce cours, vous préfixerez vos identifiants par celui de leur type (ou une abréviation autorisée pour ce type). E.g. : "inputForAddress" est un identifiant d'un élément HTML de type "Input" (Text ou Password) ; "windowOrTabForFEwithOnlyOneSentence" est un identifiant de fenêtre ou d'onglet utilisé ici. Exemples d'abréviations (de types) autorisées pour Javascript : voir ces BPs pour la création des noms de fonctions, ainsi que ces BPs pour la création des noms de constantes ou variables de programme.

2.1.2.4. Séparer+grouper les sous-parties d'un identifiant par '_', '-' et l'utilisation du style InterCap ; de plus, lorsque pertinent, utiliser une approche orientée objet pour normaliser vos identifiants

Comme illustré dans les fichiers HTML ou CSS de ce cours, '_', '-' et le style InterCap/CamelCase sont utilsables pour séparer+grouper les sous-parties d'un identifiant : une partie en style InterCap définit un groupe prioritaire par rapport à – et donc aussi incluable dans – un groupe dont les parties sont reliés par '-', lequel définit un groupe prioritaire par rapport à – et donc aussi incluable dans – un groupe dont les parties sont reliés par '_'.
Exemple :  "Exemple_d-identifiant_comprenant_une_partie-en-styleIntercap".

Pour l'approche orientée objet – l'ordonnancement des parties par inclusion / ordre décroissant de priorité (approche surtout utile pour Javascript) – voir ces BPs pour la création des noms de fonctions, ainsi que ces BPs pour la création des noms de constantes ou variables de programme.
Exemple pour HTML/CSS :  "BP_ID_partsCreation" (au lieu de "BP_for_creating_parts_within_an_ID").

2.1.2.5. Encoder des métadonnées d'un fichier dans son nom

Sur le Web, contrairement à beaucoup d'autres BPs, celles sur "quoi" (et "comment") encoder dans un nom de fichier viennent surtout d'organismes tels les universités, l'ONU ou la NASA. La section 2.1.1.3 a donné une bonne partie du "comment" : les caractères utilisables (→ ceux usuellement utilisés pour les identificateurs dans les langages formels, plus/dont '_'). Le "quoi" vient du fait qu'il est souvent utile d'encoder certaines métadonnées d'un fichier dans son nom, que l'on exploite ou pas un outil de "Gestion des Données/actifs Numériques [Digital Asset Management (DAM) systems]. À partir d'exemples de métadonnées souvent incluses dans les noms de fichiers et des autres BPs de ce document, il est possible d'effectuer la synthèse et généralisation donnée dans le paragraphe suivant.
Cette synthèse se focalise sur des noms de fichiers, pas des adresses de fichiers, la différence théorique (e.g., parmi les URIs, celle entre les URLs et les URNs) étant qu'un nom est descriptif mais du coup susceptible de changer (ce qui est un problème, en particulier pour un URI) alors qu'une adresse est un identificateur généralement généré une fois pour toute ou bien automatiquement géré par un système de telle sorte que ses changements ne créent pas de problème.

Voici des parties potentiellement utiles pour un nom de fichier, dans cet ordre, séparées par '_' :

Tout comme pour les identifiants dans des programmes (cf. section 2.1.2.2), il n'y a pas de raisons (prioritaires sur d'autres raisons) de limiter les noms des fichiers à 35 caractères maximum ou tout autre chiffre inférieur à 255 caractères (c'est la limite pour Unix, MacOs et Windows ; pour un chemin entier, la limite est de 4096 caractères sur Unix et MacOs, et d'environ 37667 caractères sur Windows). Si, pour certaines applications ou certains types de lecteurs, des noms trop longs nuisent à la compréhensibilité ou exploitabilité d'informations, il est toujours possible de masquer automatiquement certaines parties de ces noms (plus généralement, partant de ce principe de génération, comme expliqué en section 0.2.1, un auteur d'information ne doit pas restreindre sa représentation d'informations pour certaines applications ou types de personnes).

Pour les sous-parties ci-dessus et leur ordre ci-dessus, une expression régulière résumant la liste est (en anglais) :
creationDate?("_"what)*("_at-"where)*("_on-"date)*("_by-"whom)*("_when-"condition)*("_wrt-"criteria)*("."filenameExtension)?

Comme indirectement indiqué dans la liste ci-dessus, la hiérarchie de sous-partie des "quoi généraux" ["general what"] est souvent indiqué via la hiérarchie des des répertoires dans lequel se situe le fichier considéré. Certains noms pour ces répertoires sont normalisés (→ c'est une BP de les utiliser). E.g. :

2.2. BPs à propos de l'utilisation d'un langage naturel

2.2.1. Vérifier l'absence de faute d'orthographe ou de grammaire en utilisant un outil approprié

Par exemple, installez les extensions (gratuites) "LanguageTool" ("LT"; pour l'anglais, le français, ...) et "Grammarly" (pour l'anglais) dans votre navigateur, et utilisez-les en copiant les parties à vérifier (→ rendu du code HTML, mots utilisés dans les identifiants, ...) dans un éditeur de texte de votre navigateur (e.g. l'éditeur de l'extension ou un éditeur lancé par Gmail ou un autre client Web de courriel).

2.3. BPs à propos de l'utilisation d'un langage de codage

2.3.1. Utiliser au moins un validateur pour ce langage, avec ses options les plus strictes

Plus de détails ont déjà été donnés dans le dernier grand point de la section 0.2.1.3.

2.4. BPs à propos de l'environnement de codage

2.4.1. BPs destinées à éviter des pertes de temps et de focalisation cognitive (et leurs conséquences sur l'efficacité de codage et l'intérêt pour la tâche en cours)

Règle générale : plus une tâche principale a des sous-tâches mineures qui demandent du temps ou de la focalisation cognitive, plus ces sous-tâches rendront difficile la (re-)focalisation sur la tâche principale et, via cela, l'efficacité de – et l'intérêt pour – son accomplissement. Les "changements de contexte" [context switching] peuvent vous voler jusqu'à 80% de votre temps. Ces changements de contexte ou pertes de focalisation cognitives sont causés par tout ce qui change le contenu de la mémoire à court terme" ou la mémoire de travail, e.g., l'usage d'une barre de défilement (ascenseur) [scrollbar], l'ouverture d'une fenêtre par-dessus une autre, etc.

2.4.1.1. Utiliser une souris, plutôt que le pavé tactile

Selon les études/affirmations du vendeur de souris Logitech : utiliser une souris est 30% plus rapide et apporte un gain 50% de productivité. Je n'ai pas trouvé les sources (protocoles, ...) pour ces chiffres (qui peuvent donc être biaisés, voire même inventés) et tout dépend bien-sûr des gens, du pavé et de la souris. La moindre des choses reste quand même d'essayer. Venez donc au moins au 1er TD de projet avec une souris, utilisez-la et indiquez vos conclusions à votre enseignant responsable de TD lors de son évaluation de vos résultats.

2.4.1.2. Utiliser des raccourcis clavier plutôt que la souris ou le pavé tactile

E.g., pour

Au moins pour ces exemples de raccourcis, il n'y a (a priori) pas d'excuse pour ne pas les utiliser, vu la fréquence de leur utilisation, dont pour ce cours. L'usage de raccourcis est important pour éviter la perte de focalisation cognitive liée à l'usage de menus. Beaucoup de menus indiquent le raccourci clavier correspondant.

2.4.1.3. Utiliser sur tout l'écran, côte à côte, 1 fenêtre pour l'édition du code et 1 fenêtre pour l'interprétation/compilation/exécution du code

Il est beaucoup plus facile et rapide de comprendre l'origine des problèmes affichés par la seconde fenêtre si la source de ces problèmes est affiché juste à côté.
C'est comme un jeu des erreurs/différences, si les images ne sont pas côte à côte, à moins que vous n'ayez une mémoire photographique, vous allez mettre un temps beaucoup plus long que si les images sont côte à côte.
Pour les mêmes raisons de focalisation cognitive, n'ayez que ces deux fenêtres ouvertes sur votre écran (→ iconification des autres fenêtres) et ajustez la taille des fenêtres pour que celles-ci couvrent votre écran sans perdre d'espace et sans "chevauchement de fenêtres" [window overlapping].
Corollaire : configurez votre ordinateur pour éviter les mise-en-plein-écran automatiques, e.g., pour que "glisser une fenêtre en direction d'un des bords de l'écran" ne mette pas cette fenêtre en plein écran.

Tout ceci est également important pour que votre enseignant responsable de TD puisse être efficace lorsque vous lui demandez de l'aide ou lorsqu'il évalue votre travail. Vous perdrez donc des points si votre écran n'est pas couvert par ces 2 fenêtres côte à côte lors de ces demandes ou si vous n'appliquez pas cette BP lorsque votre enseignant vous la rappelle.

2.4.1.4. Utiliser au moins deux vues (sous-fenêtres) l'une sous l'autre dans votre éditeur de texte (pas 2 fenêtres indépendantes !), e.g. l'une pour du code HTML, l'autre pour du code CSS, l'une plus grande que l'autre suivant ce qu'il y a à comparer

Utilisez des "vues" (alias "buffers" ; cf. ce lien et celui-ci pour Notepad) dans votre éditeur. Si votre éditeur – qu'il fasse partie d'un environnement de développement (EDI) [IDE] ou pas – ne gère pas les vues, changez d'éditeur (et d'EDI si l'éditeur est lié à un EDI) car il est anormal qu'un éditeur ne gère pas de vues compte-tenu de leur importance pour faciliter le travail de codage. Les menus pour les vues changent suivant les éditeurs de texte ; pour l'éditeur SublimeText, si les vues sont sur le même fichier, utilisez "FILE - new view into file", sinon, utilisez "View - Layout - Rows 2" ou "Alt _" ou "Alt 2".

Il est beaucoup plus facile et rapide de comprendre comment un code (e.g. du CSS) peut exploiter un autre code (e.g. du HTML) si les sources des deux codes sont côte à côte. L'analogie avec le jeu des erreurs/différences, est ici encore plus pertinente.
Qu'il y ait des vues ne change pas le fait que pour des raisons de focalisation cognitive, chaque ligne de code doit être visible sur toute sa longueur et ne doit pas être affiché de "signe de passage à la ligne" [soft line wrapping] (ni la vue, ni l'éditeur, ni aucune fenêtre d'ailleurs, ne doit avoir à afficher un ascenseur horizontal). Pour cela, il est préférable de mettre les vues l'une sous l'autre et vos lignes ne doivent pas être trop grandes (comme indiqué en section 3.1, pour du code dans la "fonte par défaut", pas plus de 89 caractères par ligne ; réduisez ce nombre si la taille de votre écran vous impose d'avoir des lignes plus petites).
Bien-sûr, une telle limite ne peut être appliquée ne contenant qu'une adresse Web qui fait plus de 89 caractères. Pour cette exception, il convient de s'assurer que cette longue adresse Web (avec les quotes qui la délimitent si elle est utilisée pour un lien) soit seule sur sa ligne (e.g., pas d'espace avant, même si cela n'est pas conforme à l'indentation qui aurait dû être utilisée s'il y avait eu assez d'espace pour cela ; seule cette exception est prioritaire sur les règles liées à une indentation correcte).

Il est extrêmement rapide d'agrandir/réduire la taille respective des vues avec la souris suivant les besoins. C'est utile pour vous et votre enseignant responsable de TD lorsque vous lui posez une question ou lorsqu'il évalue votre travail. Vous perdrez donc des points si, lors de ces demandes ou si vous n'appliquez pas cette BP lorsque votre enseignant vous la rappelle.

2.4.2. Ne pas travailler directement sur des documents en ligne, lorsque possible

Si vous devez travailler sur des documents partagés, travaillez sur des copies locales et synchronisez lorsque c'est utile, plutôt que de travailler directement en ligne. En effet, cela réduit

Plus généralement (mais pour les mêmes raisons, notamment éviter des accès réseaux inutiles et néfastes pour la planète, e.g. voir les pages 16, 17 et 18 de ce document), il vaut mieux que tout document (e.g. une application Web) qui – comme par exemple un compilateur/interpréteur/validateur – est fréquemment accédé/utilisé alors qu'il ne change pas entre ces accès/utilisations, soit copié/installé par ses utilisateurs sur leurs machines pour être utilisé en local, si cela est possible.
E.g., dans le cours "Projet HTML", le validateur HTML+CSS et le fichier Javascript exploité par le bouton "BP check", doivent être copiés/installés et utilisés par les étudiants sur leur machine. Donc :

3. BPs relatives aux aspects concrets ou de présentation (de code ou de résultats de son exécution)

Lorsqu'elles sont appliquées à un programme, ces BPs sont des BPs de "style de programmation".

3.1. BPs pour des éléments concrets concis/compacts

Plus chaque élément concret est concis, plus d'éléments pourront être visibles simultanément (même avec des écrans de taille moyenne ou avec des logiciels ayant limites d'affichage particulières → critères d'accessibilité/mobilité) et donc comparables en minimisant l'utilisation de la mémoire à court terme, donc en minimisant la perte de focalisation cognitive. Comme l'a montré la section 2.4.1, c'est particulièrement important pour le codage.
E.g., pour comprendre/déboguer un programme, il faut souvent comparer une fonction avec celles qu'elle appelle ou par qui elle est appelée. Plus les éléments concrets pour ces fonctions sont petits, parce qu'ils adoptent un style compact et parce que les fonctions sont courtes (← suivi des critères de modularité et/ou de généricité/abstraction pour les éléments abstraits de ces fonctions), plus de fonctions peuvent être comparés simultanément, et donc plus leur analyse cognitive sera simple.

3.1.1. Limiter le nombre de caractères par ligne de code (→ pour vous, 89)

Un chiffre souvent donné pour une lisibilité maximale d'un code dans le plus grand nombre d'environnements est : 79 caractères maximum par ligne. La limite est plutôt de 75 caractères maximum par ligne pour du texte qui n'est pas du code. Lorsque Gmail envoie un message en "texte pur" [plain text], il réduit automatiquement les lignes de texte (généralement à 70 caractères par ligne mais parfois jusqu'à 83 caractères par ligne lorsqu'un mot à commencé avant la limite des 70 caractères).

Pour du texte qui n'est pas du code, 75 (ou même 70) caractères par ligne est peu contraignant : les mots sont souvent peu longs et un retour à la ligne peut souvent être inséré entre 2 mots consécutifs sans nuire à la lisibilité. Similairement, utiliser 79 caractères par ligne est souvent peu contraignant pour du texte qui n'est pas du code mais qui est structuré avec un langage de balisage tel HTML, car il est facile et lisible de mettre une balise seule sur une seule ligne si besoin. Par contre, dans un programme, les identificateurs peuvent être longs et il est plus lisible d'avoir certaines instructions sur une seule ligne ou peu de lignes. De plus, il est maintenant courant que les éditeurs de texte affichent les commentaires de code dans une fonte plus petite (→ plus de caractères par ligne possibles pour les lignes contenant un commentaire, par exemple). Par exemple, avec XEmacs, une ligne de commentaire de 89 caractères (en HTML ou C++) a la même largeur (à l'écran) qu'une ligne de 79 caractères sans commentaire ni balise HTML. Ainsi, pour un affichage avec de tels éditeurs, la limite est de 79 caractères par ligne dans la fonte par défaut.
Inversement, programmer en utilisant un petit écran peut nécessiter d'écrire des lignes plus courtes : cf. section 2.4.1.3. Il faut d'abord ajuster la taille de ses fenêtres de travail puis, à chaque fois que l'éditeur "fait apparaître un passage à la ligne" [soft line wrapping] (ou ne montre plus l'entièreté d'une ligne ; cela s'accompagne souvent de l'apparition d'un ascenseur horizontal), il faut supprimer cette apparition en ajoutant un caractère de "retour à la ligne" (ou "séparation de ligne", "fin de ligne", e.g., '\r' et/ou '\n') à un endroit approprié pour la lisibilité du code.

Dans le cadre du cours "Projet HTML", compte-tenu de la variété des éditeurs utilisés par les étudiants, la notion de "fonte par défaut" ne peut être prise en compte et le nombre de 89 caractères maximum par ligne s'avère plus adéquat ; la largeur donnée à la fenêtre de l'éditeur de texte doit donc être telle que l'éditeur fasse apparaître un passage à la ligne (ou ne montre plus l'entièreté d'une ligne) lorsqu'une ligne (sans commentaire) dépasse 89 caractères. Cette limite est de toute manière indiquée via une ligne de commentaire de 89 caractères dans les entêtes de modèles de code à utiliser pour ce cours (e.g., ce modèle pour le fichier HTML du projet). Il suffit donc d'ajuster la largeur de fenêtre de l'éditeur de texte par rapport à cette ligne de commentaire.

Note sur la "compression de code pour avoir des fichiers plus courts à transmettre" versus la "génération de code". La plupart des outils actuels pour ces deux actions (e.g., pour des fichiers Javascript ou HTML) génèrent des fichiers sans – ou avec très peu – de caractères de passage à la ligne, ce qui pollue considérablement la lisibilité des résultats de recherches lexicales via des outils affichant une ligne entière pour chaque résultat, tels beaucoup d'outils sur Unix, e.g. grep.

3.1.2. Pas de lignes vides sauf pour séparer des blocs élémentaires (fonctions, paragraphes, groupes de règles CSS de même nature, etc.)

Il vaut mieux éviter de sauter des lignes à l'intérieur d'un bloc élémentaire, non seulement pour avoir les avantages d'un style compact (voir le début de la section 3.1) mais aussi pour mieux voir ces blocs lorsqu'il n'y a pas d'autres marques pour les délimiter.
Les deux sous-sections de la section 3.1.2 illustrent cela dans le document catégorisant des BPs spécifiques à CSS.

3.1.3. Mettre plusieurs instructions (ou, en HTML et CSS, attributs/valeurs) par ligne lorsqu'il y a suffisamment de place pour cela

L'exemple (pour des règles CSS) cité dans la sous-section précédente illustre aussi cela.
Note : dans ces documents sur les BPs, les lignes normales peuvent comporter jusqu'à 140 caractères ; c'est pourquoi les lignes de code peuvent si besoin comporter 107 caractères et ne sont pas soumises à la règle des "89 caractères maximum par ligne pour les codes d'étudiants de ce cours".

3.2. BPs liées à l'indentation

3.2.1. Utiliser au moins 2 caractères supplémentaires par niveau d'indentation

Cette sous-section peut aussi être vue comme une sous-section de la section 3.1.
Une indentation d'un seul caractère par niveau n'est pas assez pour la lisibilité. Systématiquement utiliser au moins trois caractères peut conduire à des lignes trop longues.
Exemple en C, HTML et CSS, respectivement : 

void fctName ()
{ if (someCondition)
  { while (autreCondition)
    { fctName(); }
  }
}



  <div class="DivClass1">
    <div class="DivClass2">
      <ul>
      <li><p>bla bla bla</p>
      <li>bla 
      </ul>
    </div>
  </div>

    H1 { font-size:19pt;  margin-top:30% }
      H1.title
      {  font-size:17pt;  margin-top: 0% }
      H1.first {          margin-top: 6% } 
      H1.smallTopMargin { margin-top:20% }
        H1.smallTopMargin.first 
        {                 margin-top: 5% }

3.2.2. Aligner les délimiteurs de blocs horizontalement ou verticalement (sauf exception pour gagner de la place)

L'exemple en section 3.2.1 illustre les deux cas.
Plusieurs exemples de bonnes et mauvaises indentations sont données ici.
Les catégorisations en FL dans ce cours illustrent une exception systématique offrant un gain de place sans perdre en lisibilité : 

  //typically: 
  SomeType1
   \. (SomeType2
        \. e{ SomeType3
              SomeType4
            } ).


            //instead of: 
            SomeType1
             \. (SomeType2
                  \. e{ SomeType3
                        SomeType4
                      }
                ).

3.2.3. Ne pas utiliser de caractère de tabulation pour indenter

La longueur des caractères de tabulation (par rapport à la longueur des autres caractères, dans une fonte où tous les autres caractères ont la même longueur) dépend de différents paramètres, e.g. la plate-forme utilisée, l'outil d'édition/visualisation utilisée, certaines préférences enregistrées par le lecteur, etc. Si un de ces paramètres change, l'indentation d'un code est donc totalement gâchée et le code devient illisible. C'est pourquoi, ne pas utiliser de caractère de tabulation est une BP assez commune, et ce même en Python (malgré ses particularités, lesquelles conduisent certains à conseiller l'usage de 4 espaces pour l'indentation en Python).

La plupart des éditeurs de texte peuvent être configurés pour que l'utilisation de la touche de tabulation génère des espaces au lieu d'un caractère de tabulation [→ "soft tab" instead of "hard tab"]. E.g., voici comment pour Notepad, ainsi que pour Visual Studio et quelques d'autres éditeurs.

3.3. BPs liées à l'ergonomie

[Cette sous-section a été ajoutée le 8/03/2024 et signalée aux étudiants du cours "Projet HTML" durant le CM 3 de ce cours le 11/03/2024. Cette note et la couleur verte seront enlevées après le TD 02 de ce cours (-> après le 15/03/2024 18:15).]

La beauté d'un site est subjective mais il existe des BPs liées à "l'évitement d'erreurs d'ergonomie" qui sont relativement objectives.  En voici quelques classiques :