Comment décririez-vous les mathématiques dans les commentaires?

Question

Comme le dit la question ...

Une équation peut avoir plus de signification dans sa forme notée en maths que dans le code. Pouvoir mettre les maths dans les commentaires pourrait améliorer la lisibilité de mes projets.

Dans .NET btw.

Answer 1

Je viens d'utiliser plusieurs lignes pour le faire ainsi:

// Work out average as:  sum (values)
//                      --------------
//                      count (values)
//
// and distance between points as:
//           _______________________
//          /         2            2
//    d = \/ (x1 - x0)  + (y1 - y0)
//
// and the following function:
//
//             3     2   
//    f(x) = ax  + bx  + cx + d

Aucune magie requise pour cela du tout. Tu n'aimes pas l'art ASCII?

Answer 2

Suite de la réponse de @ pax à utiliser ascii-art / texte brut pour restituer vos équations (+1 à propos, pax):

Voici une liste rapide des touches de raccourci pour les caractères liés aux mathématiques:

& # 176; (degré) - Alt + 0176

& # 177; (plus / moins) - Alt + 0177

& # 178; (carré) - Alt + 0178

& # 179; (en cubes) - Alt + 0179

& # 188; (1/4) - Alt + 0188

& # 189; (1/2) - Alt + 0189

& # 190; (3/4) - Alt + 0190

Answer 3

J'utilise latex: si c'est simple, vous pouvez quand même le voir, et si c'est compliqué - coupez-le et collez-le dans la fenêtre wordpress la plus proche, la plupart du temps, ils sont analysés correctement.

Answer 4

Pour les commentaires clairs, je recourt généralement à la syntaxe de LaTeX ou de Word. Mais généralement, Word, car e. & Nbsp; g. ß est plus lisible que \ beta . Comme mes fichiers sources sont généralement au format Unicode, cela ne pose pas de problème. De plus, je n'aime pas trop d'accolades autour de tout: -)

Parfois je m'ennuyais avec Javadoc et j'utilisais beaucoup de HTML pour obtenir des formules dans Javadoc mais cela n'aide pas beaucoup à la lisibilité de la source (et exploite le fait que Javadoc uniquement utilise HTML, aucune chance en .NET ici).

J'aurais écrit l'exemple de Pax comme

// Work out average as:
//   ∑(values)/|values|
// and distance between points as:
//   d = √( (x_1 - x_0)²  + (y_1 - y_0)² )
// and the following function:
//   f(x) = ax³  + bx²  + cx + d

J'utilise rarement les sous-scripts Unicode, car ils ne figurent pas dans toutes les polices, en particulier celles qui conviennent au code:)

Answer 5

Vous savez, ce serait une excellente application pour l'extensibilité de Visual Studio affichée par ScottGu lors du dernier PDC (où il a écrit un plug-in MEF pour afficher les commentaires dans un style différent).

Vous pouvez écrire vos commentaires mathématiques à l'aide de MathML , puis créer un plug-in qui analyse le balisage et l'affiche comme une équation appropriée.

Il s’agit plus d’un commentaire «pie in the sky» que d’une réponse réelle à votre question, mais j’ai pensé que je le posterais pour que les gens réfléchissent. Peut-être que quelqu'un le fera un jour! :)

Answer 6

Cela devait être un commentaire du message de Matt, mais ma réputation est trop basse. J'ai fait quelque chose de similaire pour LaTex. Il s'agit d'un composant de compilation Sandcastle qui analyse LaTeX incorporé dans des commentaires XML et crée des images qui sont rajoutées à la documentation. C'est un simple wrapper autour de mimeTeX. Vous pouvez voir le code alphabétique à l'adresse: http://github.com/cuda/latex-sandcastle/ / a>

Answer 7

Pour moi, la meilleure façon de comprendre un problème mathématique complexe est de brancher des nombres réels et de les suivre. Lire sur son fonctionnement ne suffit pas, à moins que je ne me rappelle simplement ce que cela fait.

L’utilisation des tests Nunit serait idéale pour donner des exemples pratiques de la manière dont le problème mathématique complexe est utilisé. Utilisez peut-être simplement les commentaires pour indiquer qu’ils peuvent effectuer des tests unitaires et savoir où les trouver.

Answer 8

Pour faciliter la lecture au format ASCII des formules mathématiques, utilisez asciiTeX . asciiTeX accepte les équations de type LaTeX et les affiche au format ASCII.

Answer 9

Gardez à l’esprit ce que votre public est. Le commentaire doit avoir un sens pour vous dans les mois à venir et pour vos coéquipiers (actuels et futurs) dès maintenant. Par conséquent, si la notation mathématique est parfaitement compréhensible pour vous tous, cela pourrait aller. néanmoins, comme je ne sais pas qui lira ce commentaire, j’ajouterais une représentation textuelle ou une description.