Calendrie/NOTES.txt at main · chtoucas/Calendrie · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
Notes
=====

Comparaison avec NodaTime et les BCL
------------------------------------

### BCL

- un type date DateOnly (mais aussi DateTime) commun à tous les calendriers
- réprésentation binaire : _dayNumber (int), le nombre de jours consécutifs
  depuis l'epoch du calendrier grégorien. En clair, même si on peut construire
  une valeur de type DateOnly en spécifiant un calendrier non-grégorien, le
  résultat sera quand même une date grégorienne.

### NodaTime

- un type date LocalDate commun à tous les calendriers
- représentation binaire : YearMonthDayCalendar (int)

### Calendrie

- un type date par calendrier
- réprésentation binaire : _daysSinceEpoch (int), le nombre de jours consécutifs
  depuis l'epoch du calendrier sous-jacent

Répresenter une date
--------------------

Quatre formats de date.

1. Nombre de jours consécutifs depuis l'epoch du calendrier
Il s'agit du format utilisé par Calendrie et, dans une certaine mesure, par
la BCL.

Points forts :
- format binaire élémentaire
- obtention rapide de la propriété DayOfWeek
- ajouter ou soustraire un nombre de jours est un opération triviale
Points faibles :
- l'année, le mois, le jour du mois, le jour de l'année doivent être calculés
  à la volée, tout comme des propriétés tel que "jour intercalaire" ou
  "jour supplémentaire"

2. Année / mois / jour du mois
Format utilisé par NodaTime

Points forts :
- tout ce qui est lié à la représentation j/m/a d'une date est accessible
  immédiatement
Points faibles :
- format binaire complexe
- les propriétes DayOfYear et DayOfWeek sont calculées

3. Année / semaine / jour de la semaine

4. Année / jour de l'année

Pour un type date de type valeur, une structure, on devrait s'assurer que la
valeur par défaut est une date valide dans le calendrier sous-jacent. En général,
cette valeur correspond à l'epoch, càd le 1/1/1. Il faut donc que l'epoch
appartienne à l'intervalle de jours supportés par le calendrier.

Développement
=============

Tâches
------

Trois types de tâches : FIXME, TODO et REVIEW
Sous-catégories entre paranthèses : p.ex. TODO(code)
Trois sous-catégories : "code", "doc" et "fact"

Code C#
-------

- utilisation du mot-clé "sealed"
  - comportement par défaut des classes
  - propriétés et méthodes surchargées ("override"), tout particulièrement
    la méthode ToString()
- attribut "Pure"
- usage de "checked" ou "unchecked"
  - mode Debug : CheckForOverflowUnderflow = true
  - mode Release : CheckForOverflowUnderflow = false
  - on utilise systématiquement "checked" quand une opération peut entraîner un
    dépassement arithmétique
  - on utilise "unchecked" uniquement si nécessaire

### Règles de nommage

Constantes
- p.ex. DaysPerYear pour la constante et DaysInYear pour la propriété

### Code Analysis

Justifier l'utilisation des
- #pragma warning disable
- SuppressMessage

### Documentation XML

Utiliser <see langword="null"/>, idem pour "true" et "false".
On évitera les sections <remarks>.

### Vérifier régulièrement

- PublicAPI : les méthodes virtuelles

Tests
-----

Ne pas utiliser "." dans les noms de test car Test Explorer n’aime pas ça.
On utilise ":" ou "::" à la place.