Cómo dar formato al código en los informes de investigación

Question

Actualmente estoy escribiendo un informe de investigación formal, y incluiré el código en este informe.

Pregunta: ¿Hay alguna forma aceptada de mostrar el código en los informes de investigación? Estoy pensando tanto en términos de fuente, espaciado, etcétera, y si el código debe mostrarse dentro del documento, o en un apéndice.

El código será JavaScript y PHP. Ninguna de las secciones de código tendrá más de 25 líneas (por lo que son simples fragmentos). Habrá aproximadamente media docena de fragmentos. Cada fragmento tendrá un par de párrafos explicando lo que está sucediendo en el código y una discusión sobre sus pros/contras.

No tengo contacto con el organismo al que se enviará el informe, y no tienen directrices publicadas sobre cómo formatear el código (no cuestione estos puntos).

Answer 1

Bueno, depende de lo que la guía de estilo que se está escribiendo su papel para cumplir con ...

Por lo general, deberá ser escrito en una fuente monotipo para que sea de fácil lectura (Ej Lucida Sans consola o Courier New) . Esto significa que todas las letras ocupan el mismo espacio en la página.

Cuando escribo bits para publicar, he sangrado el código a 2.5 cm desde un lado y le doy un fondo gris claro, en una fuente de Lucida Sans Console ... siguiendo el código del estilo C, sangría.

Le preguntaría a su institución si tienen una guía de estilo, pero como no tiene esta capacidad, vaya con una guía de estilo popular como el sistema de Harvard y asegúrese de seguir el mismo formato.

Aquí está una lista de las revistas de Google Académico que muestran el estilo: http://scholar.google.com.au/scholar?hl=en&q=PHP+SQL+programming+journal&btnG=Search&as_sdt=2000&as_ylo=&as_vis=0

Answer 2

yo diría fuente Courier con un espaciado estándar de texto y espaciado de línea estándar, todo el texto negro, sangrado adecuado.

En términos del código en sí, omita las declaraciones de importación, los comentarios son correctos. Es posible que desee agregar notas al pie como {1}, {2}, en línea en el código como un comentario y referencia a continuación en el texto que explica el código.

Este papel tiene un ejemplo en la página 6:

http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-1.pdf

Answer 3

Si está escribiendo un informe de investigación, usted debe utilizar LaTeX.

Normalmente utilizo el paquete LaTeX vancyvrb y el Verbatim.

Sin embargo, otra opción es utilizar el paquete listings. Puede ingresar un archivo directamente usando el comando lstinputlisting. Numera automáticamente sus líneas y usa el carácter _ en lugar del carácter de espacio, pero esto es programable. Es realmente bastante agradable.

Answer 4

Esta es mi preferencia:

Al escribir en línea, deshacerse de código que es irrelevante para la explicación (como la importación declaraciones como se mencionó anteriormente, pero las declaraciones potencialmente también variables que son "evidentes" y similares)El objetivo del código colocado en línea debe ser una referencia cruzada fácil con el párrafo que describe ese bloque de código.

El código colocado en los apéndices debe estar completo (como en - puede poner esto en su compilador y presionar go).

No tenga miedo de colocar código muy recortado en fragmentos, junto con una referencia al apéndice que contiene el código completo: el código del apéndice es para que alguien lo lea/ejecute por separado. el código en línea es para que la gente mire y entienda el punto específico de esa sección.

Answer 5

Me doy cuenta de que esta es una vieja pregunta, ¡pero no olviden numerar las líneas de su código! Para los one-liners, está bien saltear números, pero cualquier cosa más grande, son casi obligatorios.

Answer 6

Lo dijo JD y Ben.

Debe utilizar el resaltado de sintaxis establecido y adecuado. El paquete listings de Latex, mencionado por vy32, tiene estilos de resaltado de sintaxis para Javascript y PHP, al igual que el programa Pygments, que genera, entre otros, látex, HTML y RTF.