Normas y estándares para el desarrollo de aplicaciones en CollegeOne

En college One es importante respetar las normas para la escritura de código y los
estándares de desarrollo de software que se han decidido seguir para así ayudar a la
comprensión del código entre los distintos desarrolladores, en ese sentido se
describen a continuación algunas normas obligatorias a tener en cuenta al escribir
código:
Se deben respetar los estándares de PHP PSR-2 y en especial PSR-12 que es la versión
vigente.
Se deben respetar los principios SOLID en el diseño de software.

Ambiente recomendado para el desarrollo:

Se debe usar Ubuntu server 18 o superior o homestead con la siguiente
configuración:
1. PHP7.2
a. OpenSSL PHP Extension
b. PDO PHP Extension
c. Mbstring PHP Extension
d. Tokenizer PHP Extension
2. Nginx
3. Composer
4. Git
5. Node
6. npm
7. Instalar beanstalkd para administrar las colas.
8. Instalar wkhtmltopdf en la carpeta: /usr/local/bin/wkhtmltopdf-amd64
9. Mysql 5.7
10. Instalar supervisor

Algunas normas:

Nombrando a los Controllers

Los controladores deben estar en singular, sin espacios entre palabras, la
primera letra de cada palabra debe ser mayúscula y deben terminar con la
palabra «Controller».

Bien: UserController, CreatePostController, BlogController

Mal: UsersController, User, usercontroller

Nombrando a los Métodos

Los métodos en tus proyectos de Laravel deben ser camelCase, pero con el
primer carácter en minúscula.

Bien: public function get(), public function getAll()

Mal: public function GetPosts(), public function get_posts()

Nombrando Variables

Las variables normales deben estar en camelCase (pero con la primera letra
en minúscula).

Bien: $user, $allPosts

Mal: $User, $all_posts

Por otro lado, si la variable es un array o una colección de elementos, la

variable debe estar en plural. De lo contrario, debería estar en singular.

Bien: $users = User::all(), $user = User::first()

Nombrando tablas de bases de datos en Laravel

Las tablas de base de datos deben estar en minúsculas, con guiones bajos
para separar las palabras (snake_case), y deben estar en forma plural.

Bien: posts, project_tasks, uploaded_images

Mal: all_posts, Posts, post,blogPosts

Tablas Pivot

Las tablas intermedias deben estar en minúsculas, cada modelo a los que
hagan referencia deben estar en orden alfabético. Y, deben estar separadas
por un guion bajo (snake_case).

Bien: post_user, task_user

Mal: users_posts, UsersPosts

Nombres de columnas

Los nombres de las columnas de las tablas deben estar en minúsculas, y

snake_case (los guiones bajos entre palabras). Y no debes hacer referencia
al nombre de la tabla.

Bien: body, id, created_at

Mal: blog_content_created_at , forum_thread_title, postTitle

Nomenclatura para Modelos en Laravel

Los modelos deben estar en singular, sin espacios entre palabras y en
mayúscula.

Bien: User, ForumThread,Comment

Mal: Users, ForumPosts, blogpost, blog_post, Blog_posts

#Tip: Te recomiendo que cree tus modelos y migraciones al mismo tiempo

ejecutando el comando php artisan make:model -m Post . Esto generará
automáticamente el archivo de migración.

Nomenclatura para Relaciones en Laravel

Relaciones hasOne y belongsTo

Estos deben estar en singular y seguir las mismas convenciones de

nomenclatura de los métodos del modelo (camelCase, con primera letra en
minúscula)

Por ejemplo: public function postAuthor() , public function phone()

Relaciones hasMany, belongsToMany, hasManyThrough

Su nomenclatura debe ser igual a las anteriores, pero deben estar en plural.

Por ejemplo: public function comments() , public function roles()

Relaciones Polimorfas

Para estas relaciones es recomendable utilizar la nomenclatura que nos

recomienda Laravel. Si, por ejemplo, tenemos este código:

public function category()
{
return $this->morphMany(Category::class, 'categoryable');
}

Laravel asumirá que tenemos una columna categoryable_id y otra llamada

categoryable_type.

Archivos Blade

Los archivos blade deben estar en minúsculas, snake_case (subrayado entre

palabras) agrupados en una carpeta por cada controlador y la carpeta se
debe nombrar con minúscula y en snake_case(user_role). Y, si son
templates de elementos que normalmente se renderizan por medio de una
interación (con @foreach, por ejemplo), se les debe agregar un guion bajo al
comienzo.

Por ejemplo: index.blade.php,  all.blade.php , _item.blade.php

Rutas

Las rutas se deben nombrar en singular y con en minúscula (snake_case).

Se debe hacer uso de grupos de rutas para los middleware y para las rutas
de un mismo controlador, se debe hacer uso también de la función
Route::resource que proporciona las rutas por defecto de todo controlador.

Bien: 
Mal:

Archivos de recursos

Todos los archivos de recursos css y js deben ir en la siguiente carpeta:

public/assets en la respectiva carpeta según el tipo de archivo, subcarpeta
css para los archivos de estilo, subcarpeta js para los archivos de javascript y
así con cada tipo de archivo.

Puntos a tener en cuenta según tipos de archivos:

1. Archivos de estilo CSS

a. Ubicación: public/assets/css
 b. Se deben ubicar en una subcarpeta si son específicos para una
sección, la sub carpeta debe tener el mismo nombre que la ruta
de la sección.

c. La nomenclatura para nombrar los archivos es la siguiente:

nombre_archivo_version.min.css

d. Los archivos de librerías no se deben renombrar y para evitar

conflictos de nombre cada librería / plugin se debe colocar en
una subcarpeta (con el nombre del plugin, ejemplo: bootstrap_4)
de public/assets/plugin, si ya viene agrupado en una carpeta
dejar el nombre original.

2. JS

a. Ubicación: public/assets/js

b. Se deben ubicar en una subcarpeta si son específicos para una

sección, la sub carpeta debe tener el mismo nombre que la ruta
de la sección.

c. La nomenclatura para nombrar los archivos es la siguiente:

nombre_archivo_version.min.js

d. Los archivos de librerías no se deben renombrar y para evitar

conflictos de nombre cada librería / plugin se debe colocar en
una subcarpeta (con el nombre del plugin, ejemplo: bootstrap_4)
de public/assets/plugin, si ya viene agrupado en una carpeta
dejar el nombre original.

3. FONTS

a. Ubicación: public/assets/fonts.

b. Los archivos de fuentes no se deben renombrar.

4. ICONS
 a. Ubicación: public/assets/icons

5. IMG

a. Ubicación: public/assets/img

6. Plugins Java script y css

a. Ubicación: public/assets/plugins

b. Si ya vienen agrupados en una subcarpeta dejar tal cual y si

vienen los archivos sueltos crear una carpeta con la siguiente
nomenclatura: nombre_plugin_version

7. El FrontEnd se debe desarrollar en vue.js y en el caso que se haga

con jquery o java script puro se debe desarrollar de manera modular,
nuca se deben crear funciones globales y siempre debe estar en
archivos .js. Solo se permite declaraciones de variables globales con
propósitos específicos, como usar mensajes de las traducciones u
obtener datos desde php. Para crear los módulos de java script se
debe seguir el siguiente tutorial:

a. https://www.c-sharpcorner.com/article/the-javascript-module-pattern-used-
with-jquery/

b. https://medium.com/@crohacz_86666/basics-of-modular-javascript-
2395c82dd93a

c. Y en el mismo proyecto hay ejemplos varios ejemplos como los son los
archivos: public\assets\js\js.js, public\assets\js\invoice\invoice.js entre otros.

Puntos importantes:

1. Se debe tratar en lo posible de NO mezclar múltiples lenguajes como

en el siguiente ejemplo:
2. Se deben evitar errores de sintaxis que en tiempo de ejecucion no
afecten pero si se marquen en el editor.

3. Se deben utilizar las ultimas caracteristicas de la version de php que se

esta usando(7.1), y evitar funciones como por ejemplo isset(), array()
entre otras que ya no son realmente necesarias.

4. Se deben evitar archivos con muchas lineas de codigo, bien sean

controladores, modelos entre otros.

5. Se debe tratar en lo posible de usar tipos estrictos en php, esto no es

mas que especificar los tipos de las variables, parametros y retornos de
funciones, ejemplo:
6. Se debe trabajar con inyecion de dependencias siempre que sea
posible.

7. Evitar funciones que retornen cosas distintas según alguna condición,

en lo posible especificar qué tipo de dato debe retornar y cuáles son
los tipos de los parámetros en la firma de la misma, ejemplo:

8. Los controladores solo deben tener en la medida de lo posible los

métodos públicos de acciones y todos los otros métodos se deben
trasladar a traits y otras clases pertinentes.

9. Usar tipos estrictos ayuda a evitar problemas en funciones que deben

cálculos, problemas a la hora de leer el código entre otros.

10. En las relaciones entre tablas siempre se deben especificar la clave

foránea.
 11.Prohibido terminantemente subir código temporal a github, se debe
subir solo código funcional y no comentado y se deben hacer commits
de las tareas a diario de ser posible al finalizar la jornada.

12.Los métodos que retornen contenido json bien sea desde el api o los
otros controladores lo deben hacer en este formato:

Conclusión

Seguir una norma de nomenclatura nos ayuda a tener un código prolijo,

entendible y estandarizado. Veras que, si te acostumbras a utilizar estas
normas, el código de otra persona se sentirá como propio y no nos generará
esa sensación de caos que a veces nos da cuando leemos el desarrollo de
alguien más.

http://youmightnotneedjquery.com/

https://www.freecodecamp.org/news/javascript-modules-a-beginner-s-guide-
783f7d7a5fcc/

https://www.flickr.com/photos/qubodup/16258492451If

http://freecodecamp.org/