¿Cómo describirías las matemáticas en los comentarios?

Question

Bueno, como dicen las preguntas ...

Una ecuación podría ser más significativa en su forma anotada en matemáticas que en el código. Ser capaz de poner matemáticas en los comentarios podría mejorar la legibilidad en mis proyectos.

En .NET por cierto.

Answer 1

Solo uso varias líneas para hacerlo así:

// 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

No se requiere magia para eso en absoluto. ¿No te encanta el arte ASCII?

Answer 2

Siguiendo con la respuesta de @ pax para usar ascii-art / texto plano para representar tus ecuaciones (+1 por cierto, pax):

Aquí hay una lista rápida de teclas de acceso directo para caracteres relacionados con las matemáticas:

° (grado) - Alt + 0176

± (más / menos) - Alt + 0177

² (cuadrado) - Alt + 0178

³ (en cubos) - Alt + 0179

¼ (1/4) - Alt + 0188

½ (1/2) - Alt + 0189

¾ (3/4) - Alt + 0190

Answer 3

Uso látex: si es simple, puedes verlo de todos modos, y si es complicado, córtalo y pégalo en la ventana de wordpress más cercana, la mayoría de las veces se analizan correctamente.

Answer 4

Para comentarios simples usualmente recurro a la sintaxis de LaTeX o Word. Pero usualmente Word, desde e. & Nbsp; g. ß es más legible que \ beta . Dado que mis archivos de origen suelen ser Unicode, esto no plantea ningún problema. Tampoco me gustan muchos frenillos alrededor de todo :-)

Algunas veces me aburrí con Javadoc y usar mucho HTML para obtener fórmulas en Javadoc se muestra a la perfección, pero eso no ayuda a la legibilidad de la fuente (y explota el hecho de que Javadoc solo se basa en HTML, sin suerte en .NET aquí).

Habría escrito la muestra de Pax como

// 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

Raramente uso subíndices Unicode, ya que no están en todas las fuentes, especialmente no son las adecuadas para el código :)

Answer 5

Ya sabes, esta sería una gran aplicación para la extensibilidad de Visual Studio que ScottGu mostró en el último PDC (donde escribió un complemento de MEF para mostrar los comentarios en un estilo diferente).

Puede escribir sus comentarios matemáticos utilizando MathML , y luego agregue un complemento que analiza el marcado y lo muestra como una ecuación adecuada.

Esto es más un comentario de pastel en el cielo que una respuesta real a tu pregunta, pero pensé que lo publicaría para que la gente piense. ¡Tal vez alguien lo haga algún día! :)

Answer 6

Esto iba a ser un comentario de la publicación de Matt, pero mi reputación es demasiado baja. Hice algo similar para LaTex. Es un componente de compilación de Sandcastle que analiza LaTeX incrustado en comentarios XML y crea imágenes que se agregan a la documentación. Es un envoltorio simple alrededor de mimeTeX. Puede ver el código alfa en: http://github.com/cuda/latex-sandcastle/

Answer 7

Para mí, la forma más fácil de entender un problema matemático complejo es ingresar algunos números reales y seguirlo. Leer sobre cómo funciona no es suficiente a menos que simplemente me esté recordando lo que hace.

Usar las pruebas de Nunit sería ideal para dar ejemplos prácticos de cómo se usa el complejo problema matemático. Tal vez solo use los comentarios para señalar que existen pruebas unitarias por las que se pueden analizar y dónde encontrarlas.

Answer 8

Para facilitar un poco más la representación ASCII de las fórmulas matemáticas, hay asciiTeX . asciiTeX acepta ecuaciones de estilo LaTeX y las imprime en ASCII-art.

Answer 9

Ten en cuenta lo que es tu audiencia. El comentario debe ser significativo para usted dentro de unos meses y para sus compañeros de equipo (presente y futuro) en este momento. Por lo tanto, si la notación matemática es perfectamente comprensible para todos ustedes, esto podría estar bien; aún así, dado que no puedo saber quién leerá ese comentario, agregaría una representación o descripción textual.