Guía de estilo general

PROPIEDADES DE LOS ARCHIVOS

TIPOS DE ARCHIVOS

• Se permiten todos los archivos que no estén contemplados en el .gitignore, que podrá ser editado a discreción de los administradores del repositorio.

NOMBRES DE ARCHIVOS

• Los nombres de archivo deben seguir la sintaxis Tema/Práctica/Relación... nº - Título.
  • Tema 6 - Funciones
  • Práctica 6 - Newton Raphson
• Los nombres de archivo nunca llevarán un identificador de su asignatura, para eso está el árbol de carpetas.

CONTENIDO DE LOS DOCUMENTOS

TITULACIÓN (prefijo #)

• El prefijo # queda reservados para la cabecera del documento.
  • Las cabeceras de los documentos deben seguir la sintaxis # TEMA/PRÁCTICA/RELACIÓN... nº - TÍTULO.
    • # TEMA 6 - FUNCIONES
    • # PRÁCTICA 6 - NEWTON RAPHSON
• Cada prefijo # hasta cinco # denota una subsección del anterior con un # menos.
• Cada subsección debe ir precedida y sucedida de una línea en blanco.
• Cada subsección debe contener un número que identifique su apartado dentro del archivo, nunca el índice del archivo dentro del repositorio.
• El prefijo ###### denota un comentario o una anotación a tener en cuenta, no un apartado del documento.

Ejemplo de titulación:

# TEMA 1 - PRINCIPIOS BÁSICOS

## 1.1 - Definiciones

### 1.1.1 - Primera definición

Contenido de la definición.

###### Comentario o anotación sobre la primera definición.

### 1.1.2 - Segunda definición

#### 1.1.2.1 - Apartado de la segunda definición

Contenido del apartado de la segunda definición

PÁRRAFOS

• Los párrafos deben ir separados entre sí por una línea en blanco y no deben contener sangría de primera línea.
• Se recomienda una longitud de párrafo de entre 3 y 20 líneas.
• Cada párrafo debe explicar una idea o un concepto. Si un párrafo se hace demasiado largo, se ha de intentar dividirlo en varios para diferenciar sus ideas.
• Los párrafos de una sola línea deben estar escritos de la forma más resumida posible.
• Se procurará evitar las líneas huérfanas y viudas.

PIEZAS DE CÓDIGO SIMPLE

• Las piezas de código simple son aquellas que se introducen en el interior de un párrafo.
• Deben incluirse como código simple los siguientes elementos:
  • Caracteres o símbolos a los que se refiere el texto, sin precederlos de el carácter o entradillas similares.
  • Nombres de palabras reservadas, funciones, variables u otros elementos de código.
  • Entrada y salida estándar.

PIEZAS DE CÓDIGO COMPLEJO

• Las piezas de código son aquellas que se introducen fuera de un párrafo.
• Deben ir precedidas y sucedidas por una línea en blanco.
• Deben ir precedidas de tres caracteres `, que pueden contener el lenguaje en el que se escribe dicho código justo después.
• Los scripts deben ir precedidos de su título, que va precedido de seis #.
  • Éstos son los únicos en los que se ha de dejar una línea en blanco precedente.
• Los ejemplos de entrada y salida en consola no deben venir declarados en ningún lenguaje.
  • Las entradas en consola van precedidas de $ y un espacio.
  • Las salidas de consola van precedida de dos espacios.

Ejemplo de código complejo:

#include <iostream>
using namespace std;

int main() {
   cout << "Hello, World!";
   return 0;
}

LISTAS

• Los elementos de las listas se declaran mediante -, nunca mediante otro carácter.
• Las listas deben contener un espacio en blanco entre el párrafo anterior y su primer elemento.
• Todos los elementos de la lista deben acaban con su signo de puntuación correspondiente.
• La jerarquía de elementos debe crearse con dos espacios en blanco cada vez.
• Si se enumeran conceptos junto con sus definiciones en una lista, el concepto sucedido de : debe ir en negrita.

TABLAS

• Las tablas pueden seguir dos estructuras:
  • Organizacion vertical: Se declaran los elementos de las columnas EN MAYÚSCULA en la cabecera.
  • Organización horizontal: No existe cabecera, todos los elementos deben ir declarados en negrita, incluidos los de la cabecera.
• El formato de las tablas se especifica sólo con tres - y : en las posiciones que corresponda.
• Si una columna no fuera lo suficientemente ancha, se debe añadir   a ambos lados de la cadena de su cabecera para ampliarla
  • El número de espacios declarados a ambos lados debe ser idéntico.
• Si una tabla consta de una columna de términos y otra de definiciones, la de términos debe ir declarada como código si se trata de elementos informáticos y siempre en negrita.
  • En ambos casos, la columna de términos debe ir centrada y la de descripciones o definiciones sangrada naturalmente.
• Más información sobre tablas aquí.

IMÁGENES

• Deben tener la mayor resolución posible, en formato .png preferentemente.
• Se recomienda darles un nombre lo más descriptivo posible, ya sea por su contenido o por el punto en el que se encuentran.
• Deben incluirse en un directorio específico para imágenes dentro del mismo directorio en el que se encuentre el archivo que las utiliza.
  • Se recomienda que dicho directorio de imágenes se llame .img para crear una consistencia con el resto de asignaturas.

Ejemplo de árbol de directorios con directorio de imágenes:

.
└── Fundamentos del software
│   └── Prácticas
│       ├── .img
│       │   └── practica0_apartado2.png
│       │   └── diagrama_gcc.png
│       ├── Práctica 0 - Introducción a Unix y Linux.md
│       ├── Práctica 1 - Órdenes básicas de Unix Linux.md
│       ├── Práctica 2 - Permisos y redirecciones.md
│       └── Práctica 3 - Variables, alias, órdenes de búsqueda y guiones.md
└── README.md

NORMAS ESPECÍFICAS A LA WIKI

• En las páginas de la wiki se pueden crear varias secciones de una sola #, ya que el título de la página se muestra fuera del documento.