Hola a todos, he estado ocupado recientemente y las actualizaciones se han vuelto irregulares. A continuación, haré todo lo posible para que compartir sea más estable... Síganme, recopilen, me gusta... Muchas gracias.
prefacio
No sé si he encontrado que muchos proyectos excelentes de código abierto a menudo tienen una estructura de código clara y anotaciones completas. Tanto su legibilidad como su escalabilidad son muy poderosas. Tengo mucha envidia. Por lo tanto, cómo escribir código limpio y excelente es el primer paso para el ascenso al hermano mayor;
En este punto, algunos amigos pueden preguntar, ¿qué tipo de código es un código limpio? No se preocupe, esta pregunta es la conclusión a la que finalmente llegamos, y luego registre algunos puntos que personalmente creo que son necesarios para un código limpio;
convenio de denominación
El primero, por supuesto, son las reglas de nomenclatura. Al mirar el código fuente de proyectos tan excelentes como Vue, descubrí que hay relativamente poco contenido relacionado con las anotaciones, pero a través del nombre del método, el nombre de la función, el nombre de la variable, etc. ., podemos ver a grandes rasgos su contenido.Cuál es la función, aquí está el llamado naming debe tener su significado correspondiente en lugar de escribir lo que se nos ocurra , por ejemplo:
function UsEntity(){
// 代码
}
const us = new UsEntity();
En este ejemplo, se define una función UsEntity, y parece que debería ser una función constructora, porque de acuerdo con la convención, la primera letra está en mayúscula y hay una palabra Entity que significa una instancia, y también se usa a continuación, si no escribes un comentario Solo basándonos en el nombre, no podemos adivinar la función específica de este código con alta probabilidad, por lo que obviamente esto no es muy bueno, si lo cambias
function User(){
// 代码
}
const user = new User();
Entonces esto es muy claro, es decir, el usuario, define una función constructora sobre el usuario, e instancia un usuario debajo, la próxima operación también debe estar relacionada con el usuario; de
esta manera, un buen nombre es realmente importante, puede Ayúdanos a comprender rápidamente la función general de una función o variable cuando los comentarios o documentos relacionados no son tan completos ;
entonces la pregunta es, ¿cómo es la regla de nomenclatura? Creo que esta sigue siendo la puntuación:
Variables y constantes
Para variables y constantes, sus funciones se usan a menudo para almacenamiento de datos, control de estado, etc. Creo que las reglas más apropiadas son: sustantivo o frase + adjetivo :
// 用户信息
const user = {
};
const age = 12;
const name = "oliver";
// 验证结果，比如是否已登录
const isLogin = false;
Personalmente, creo que esto es más apropiado. Relativamente a través del nombre de la variable, podemos ver su función general. Además, a menudo usamos el caso del camello pequeño para el nombre de la variable , pero esto no es absoluto. Esto debe definirse de acuerdo con cada equipo. Para las constantes , generalmente usamos la especificación de mayúsculas , y las palabras están separadas por guiones bajos, por ejemplo:
const USER = {
};
En este punto, algunos socios pequeños pueden decir que esta denominación es demasiado simple. En proyectos reales, a menudo se repite. En este momento, podemos describir esta variable con más detalle, pero el grado de atención no debe ser demasiado. Eso manera Parecerá demasiado redundante. Por ejemplo, para los datos almacenados en primer plano, generalmente usamos usuario para la información del usuario almacenada en primer plano, pero si hay varios usuarios, entonces podemos agregar algunos prefijos
// 比如，已经认证过的用户
const authenticatedUser = {
};
// name
const firstName = "";
// 是否激活
const isActiveUser = false;
Pequeño
tema de ejercicio: denominación de la información de usuario almacenada
// 比较差的命名
const u = {
};
const data = {
};
Este es el tipo de denominación que personalmente creo que es relativamente pobre, porque el usuario no se puede ver en absoluto al mirar el nombre de la variable, y el alcance de los datos es demasiado amplio, y muchos datos se pueden representar con datos;
// 正常
const userInfo = {
};
const userData = {
};
Algunos amigos pueden decir, esto no es muy bueno, ¿por qué solo puedo decir normal? Personalmente, creo que el nombre de la variable es un poco redundante , el usuario también es un sustantivo, ya puede representar la variable actual utilizada para el contenido relacionado con el usuario, puede no es necesario agregar información y datos;
// 比较好的
const user = {
};
const customer = {
};
Para un mejor naming, debe ser lo suficientemente conciso y poder explicar su propósito, el usuario y el cliente pueden explicar completamente su función y son muy concisos, por lo que personalmente creo que es más apropiado;
funciones y metodos
Para las funciones y los métodos, su función suele ser realizar algunas operaciones o comandos, y calcular algunos resultados, como solicitar interfaces y validar formularios.Creo que las reglas más apropiadas son: verbos o frases + adjetivos :
// 发送用户信息
function sendUser(){
};
// 获取用户信息
function getUser(){
};
Para funciones y métodos, generalmente seguimos la especificación del caso de camello pequeño , a menos que la función sea un constructor . Para los constructores, acordamos nombrarlos en caso de camello grande ;
de manera similar, los nombres de funciones y métodos también pueden describirse más detalladamente, pueden aumentar su precisión y la posibilidad de que no haya nombres duplicados, como
// 获取用户信息
function getUserByPhone(){
};
Esto es muy adecuado, y puede ver la función de esta función de un vistazo, obtener al usuario a través del número de teléfono móvil y, por supuesto, alguna verificación, calcular el valor booleano:
function phoneIsValid(){
}
Debería poder ver la función de esta función mirando el nombre, para determinar si el teléfono ha pasado la función de verificación;
Pequeño tema de ejercicio
: Almacenamiento de información de usuario en una base de datos
// 比较差的
function handle(){
}
Creo que esto es relativamente pobre, o la razón de la variable anterior, el alcance es demasiado amplio, a través del identificador del nombre de la variable, podemos saber que se trata de una operación, pero no sabemos la operación específica en absoluto, obviamente, esto no encaja muy bien;
// 正常
function save(){
}
Esto es relativamente mejor. Sabemos que esta es una función de guardar, pero en el proceso de escritura, tal vez podamos saber qué es guardar, pero después de un período de tiempo, solo podemos saber que esta es una operación de guardar con solo mirando el nombre. , se desconoce por completo qué save;
en comparación con handle, la ventaja de save es que puede saber específicamente el tipo de una operación, pero se desconoce para qué es esta operación;
function saveUser(){
}
Obviamente, esta intención es relativamente clara, es decir, salvar a los usuarios, por lo que este tipo de cosas son más apropiadas y mejor nombradas;
clase de clase
Para la clase class, creo que el mayor uso es construir cosas abstractas, como usuarios y productos.Para esto, siento que sus reglas pueden ser similares a las variables, y las reglas son más o menos las mismas: sustantivos o frases + adjetivos :
// 用户
class User{
}
class Customer{
}
// 飞机游戏
class PlaneGame{
}
Para el nombre de la clase, a menudo usamos el caso del camello grande, porque la definición de la clase es a menudo el constructor;
Pequeño
tema de ejercicio: definir un objeto de usuario;
// 较差的
class UEntity{
}
Este tipo es relativamente pobre, y no puedo ver cuál es su significado en absoluto... Solo puedo sentir que es una entidad de U, y no puedo adivinar;
// 普通的
class UserObj{
}
Esto es muy común Mirando el nombre, podemos saber que esta es una colección obj sobre el usuario, pero es un poco redundante.
class User{
}
class Admin{
}
Esto es muy bueno. Puede conocer su función directamente mirando el nombre. Admin es la división de autoridad específica del Usuario. A veces necesitamos información más específica del usuario, por lo que puede representarse con un nombre más específico;
otro
No se recomienda describir variables con más de 3 palabras, como
// 不太建议
const userWithNameAndAge = ""
Aunque podemos saber rápidamente su función y significado mirando el nombre, en realidad es demasiado redundante. El nombre y la edad son generalmente atributos fijos del usuario. De hecho, el nombre y la edad no son necesarios.
// 新用户
const newUser = "";
// 已登录用户
const loggedInUser = "";
Estructura y formato del código
notas
Antes que nada, debemos aclarar que los comentarios son explicaciones y descripciones del código, el propósito es que los demás entiendan las funciones y el negocio de manera más fácil y rápida al leer el código escrito por el autor, por lo tanto, los buenos comentarios pueden ser se utiliza para crear sinergias y cambiar errores. Un mal comentario es un completo obstáculo. No lo entendí al principio, pero después de leer el comentario, es aún más ambiguo...
mala nota
Solo mira el ejemplo
// 冗余的注释
function getUserName(type) {
if (type === "first") {
// 如果type的值等于first返回first name
return "first name";
} else {
// 否则返回last name
return "last name";
}
}
¿Qué tiene de malo esto? Obviamente, podemos comprender rápidamente el significado del código sin leer los comentarios, pero una vez que se escriben los comentarios, debemos hacer un esfuerzo adicional para leerlos, lo cual no es adecuado. La intención original de los comentarios es ayudar a una lectura más rápida. , aquí hay un poco de poner el carro delante del caballo ;
El segundo tipo de comentario también es molesto , es decir , el nombre de la variable y el comentario están en conflicto , como
// 变量名和注释冲突
function insertUser(user) {
this.dbEngine.insert(user) // 更新用户
}
Es similar a esto. Insertar generalmente representa inserción, pero el comentario aquí es actualizar. La palabra que generalmente se usa para actualizar es actualizar, por lo que una vez que otros desarrolladores ven este comentario, tienen que mirar la implementación específica. Lógica, para determinar si esto el método es insertar o actualizar, por lo que la anotación debe ser coherente con el nombre de la variable y no puede ser engañosa ;
El tercer tipo de comentario es el código comentado . En realidad, es bastante inútil. A medida que el proyecto se hace más y más grande, el código incierto en ese momento se comenta temporalmente. Tal vez la intención original en ese momento era tener otra solución, pero no necesariamente Sí, el código comentado debe guardarse temporalmente, pero a medida que avanza el desarrollo, el código comentado a menudo se conserva para siempre, y la persona que se hace cargo no se atreve a eliminarlo a voluntad, por lo que en este caso generalmente hay dos recomendados:
- Al revisar el código, asegúrese de revisar el código comentado, revise la situación después del descubrimiento y determine si es necesario eliminarlo;
- Una vez que se determina la función, el desarrollador debe eliminar conscientemente el código comentado, de lo contrario, el pozo se mantendrá para siempre;
buena nota
Si hay malos, debe haber buenos. Los buenos comentarios generalmente incluyen lo siguiente:
- Información de derechos de autor , incluida la hora, la versión, la información legal, la información del autor, etc., que puede ayudar rápidamente a otros a ponerse en contacto con el autor cuando tengan preguntas;
- Suplementos a nombres de variables , como información que no puede ser descrita por nombres de variables,
// 邮箱 [text]@[text].[text]，邮箱只有一个"@"和一个"."
const emailRegex = /\S+@\S+.\S+/
- La descripción de la información de advertencia , como que algún código tiene aplicabilidad o puntos de atención funcionales, se puede expresar a través de comentarios.
// 仅使用于浏览器环境
localStrage.setItem("user","name")
- Código sin terminar , como cuando el código no se escribió debido a razones especiales, puede escribir una nota para recordar
function getUser(){
// 待办事项，需要实施
}
formato de código
El formato de código se divide simplemente en dos tipos, uno es entre líneas (como líneas en blanco entre líneas) y el otro es entre la misma línea (como sangría), pero pase lo que pase, el propósito es mejorar la legibilidad;
línea a línea
En principio el código entre líneas no debe tener demasiados saltos, simplemente no es para que la gente se desplace de un lado a otro, para lograr este propósito generalmente tenemos las siguientes consideraciones
- Considere dividir archivos con múltiples conceptos Por ejemplo, hay muchas clases en un archivo, entonces puede considerar dividir cada clase como un archivo en este momento;
- En el mismo archivo, las diferentes "áreas" deben estar separadas por intervalos Por ejemplo, en una interfaz funcional grande, hay dos funciones de agregar y modificar , por lo que las funciones relacionadas recién agregadas deben escribirse juntas y las relacionadas modificadas también deben escribirse juntos;
- En el mismo archivo, las funciones relacionadas deben estar lo más cerca posible , como agregar y consultar. Generalmente, necesitamos actualizar el contenido de la tabla después de que el contenido de la tabla se agregue con éxito. Si las dos áreas están muy separadas en esta vez, entonces causará inconvenientes a nuestra lectura, como el siguiente ejemplo:
// 起始
function start(){
next()
}
// 下一步
function next(){
last()
}
// 结尾
function last(){
}
Este tipo de relativo es más razonable, las funciones están escritas en orden, así que al leer, puedes leer en orden, lo que facilita mucho nuestra comprensión;
Misma línea
Personalmente creo que el punto más importante en las reglas de la misma línea es que la línea de código se pueda leer normalmente sin hacer scroll horizontal , es decir intentar que no aparezcan barras de scroll, por lo general tendremos las siguientes reglas:
- Sangría , la sangría debe determinarse de acuerdo con la situación real del equipo, una pestaña puede ser de 2 espacios o 4 espacios;
- Dividir oraciones largas en múltiples oraciones cortas , esta división ayudará a la comprensión lectora;
resumen
La primera sección de este artículo explica cómo escribir para facilitar la lectura y la comprensión de las reglas de nomenclatura de variables, funciones, clases, etc. La segunda sección describe algunos puntos de atención durante el desarrollo, desde comentarios hasta formatos de código . El resumen general es como sigue:
- Las reglas de nomenclatura de variables, funciones y clases se pueden describir mediante: sustantivo o frase + adjetivo ;
- Los buenos comentarios pueden complementar y ayudar a los lectores a comprender rápidamente al leer el código. Demasiados comentarios y comentarios engañosos aumentarán en gran medida el costo de la comprensión;
- Hay que juzgar si existe cierta correlación entre la zona superior y la zona inferior entre las líneas del código , si la hay no es necesario separarla, si no es así dividirla en líneas en blanco;
- Debe haber sangría entre la misma línea , y la longitud del código no debe ser demasiado larga para que aparezcan barras de desplazamiento ;