Desarrollé un formateador de C, C++, Java y JavaScript con Clang para entornos Node.js.
(github.com/lumirlumir)- Repositorio de GitHub: https://github.com/lumirlumir/npm-clang-format-node
- Sitio oficial de documentación: https://clang-format-node.lumir.page/
¡Hola!
Desarrollé un formateador de C, C++, Java y JavaScript usando Clang en un entorno Node.js. Este proyecto comenzó de nuevo basándose en el paquete clang-format de Angular, que ya no recibe mantenimiento.
Hace dos o tres meses compartí algo similar, y esta vez publiqué la versión v1.3.0, además de agregar un sitio de documentación detallado para que a los usuarios les resulte más fácil y cómodo usarlo. Pueden revisar el sitio de documentación aquí; incluye desde la forma básica de instalación hasta las razones para usar este paquete, así que creo que puede ser útil para quienes estén interesados.
En esta actualización agregué varias pruebas para aumentar aún más la estabilidad del paquete, y también se añadieron nuevas funciones.
Todo este paquete está bajo licencia MIT y puede usarse libremente.
¿Qué tipo de proyecto es clang-format-node?
Este paquete es un paquete de Node.js basado en clang-format de Clang, famoso por ser el compilador de C de LLVM, y ofrece formateo de código para C, C++, y Java. En pocas palabras, cumple un rol similar a Prettier dentro de un entorno Node.js, pero se diferencia en que ofrece formateo para C, C++ y Java, lenguajes que Prettier no soporta.
En particular, clang-format-node resulta útil cuando necesitas escribir código JavaScript junto con código C/C++, como en el desarrollo del core de Node.js o de Electron.
El paquete clang-format existente tenía la molestia de requerir la instalación de dependencias adicionales que dependen del sistema operativo, como Ubuntu, pero con este paquete puede usarse de inmediato sin instalaciones extra. Además, mientras que el paquete anterior tenía aspectos complicados para integrarse en flujos de trabajo de CI basados en Node.js y npm, clang-format-node puede usarse fácilmente simplemente instalándolo desde npm y configurando un script, lo que ofrece muchas ventajas en entornos de CI.
Entonces, ¿cuáles son las características del paquete clang-format-node?
1. Un Drop-in Replacement para reemplazar clang-format de Angular
clang-format-node es un Drop-in Replacement que permite sustituir fácilmente el paquete Angular/clang-format.
Cambiar del paquete existente a clang-format-node es muy sencillo, y puede usarse de inmediato sin procesos complejos.
2. Solo Node.js es suficiente, sin dependencias adicionales para usar Clang
No se necesitan en absoluto dependencias adicionales como Python o C++. Con solo Node.js se puede ejecutar fácilmente.
3. Amplio rango de soporte
Ofrece amplio soporte para distintos sistemas operativos y arquitecturas, versiones de Node.js, imágenes de runners de GitHub Actions, imágenes de build de Docker y más.
4. Configuración sencilla de CI
Sin configuraciones complejas, puedes usar clang-format-node igual que cualquier otro paquete de Node.js.
5. Builds y releases automatizados
Cada vez que se actualiza clang-format, se publica automáticamente una nueva versión en npm. GitHub Actions detecta periódicamente las actualizaciones, compila el paquete y genera un Pull Request.
Formatear código con clang-format y git-clang-format
(El texto de abajo es una traducción parcial al coreano de lo que escribí en inglés en la sección https://clang-format-node.lumir.page/docs/get-started/introduction.)
La importancia del formateo de código
Da formato al código siempre
El formateo de código es una tarea muy importante para mejorar la calidad del código. La clave del formateo es mantenerlo de forma consistente para aumentar la legibilidad y la facilidad de comprensión.
¿Qué es clang-format?
clang-format es una herramienta que formatea automáticamente archivos fuente de lenguajes como C y C++, y fue desarrollada como parte del proyecto open source LLVM Clang.
Cómo funciona
- Crear un archivo de configuración
Se crea un archivo de configuración (.clang-format) que define el estilo de formateo. - Ejecutar el comando
Al ejecutar el comandoclang-format, el código fuente se reorganiza automáticamente según esas reglas de estilo.
Características principales
- Soporte para múltiples lenguajes
Soporta varios lenguajes como C, C++, Java, JavaScript, Objective-C, Protobuf y C#. - Ejemplo de comando de formateo
Al ejecutar este comando, el archivoclang-format -i my_source.cppmy_source.cppse formatea automáticamente según el estilo especificado.
Ejemplo de formateo de código
// Before formatting
void test(QString&data, bool extraString) {
int i=0;
for (i=0;i<3;i++) {
data+="reallylongstringtoproducealonglineasanexample" + QString::number(i * 1000) + "/filetoload.html";
if (extraString)
{
data += "some-extra";
}
}
}
// After formatting
void test(QString &data, bool extraString)
{
int i = 0;
for (i = 0; i < 3; i++) {
data += "reallylongstringtoproducealonglineasanexample" + QString::number(i * 1000)
+ "/filetoload.html";
if (extraString) {
data += "some-extra";
}
}
}
El ejemplo de arriba muestra cómo clang-format da formato al código. Las reglas de formateo pueden configurarse libremente según el estilo del equipo.
Problemas de clang-format
clang-format es una herramienta excelente, pero puede provocar problemas con el código existente y el historial de commits.
Problemas principales
- Conflictos con el código existente
Si se formatea el archivo completo, también cambian partes no relacionadas con el formateo, lo que genera cambios innecesarios. - Confusión en el historial de commits
Los cambios masivos de formateo pueden volver más complejo el historial de commits y dificultar el merge de ramas, el code review y el análisis del código. - Inconsistencia entre código nuevo y código existente
Al agregar código nuevo a código ya formateado, puede ser difícil mantener el formateo.
Solución: git-clang-format
git-clang-format es una herramienta de extensión de Git que ayuda a aplicar formateo solo al código modificado. Al usarla, se obtienen ventajas como estas:
- Minimizar el alcance del formateo: aplicar formateo solo al código modificado
- Simplificar la revisión: revisar por separado los cambios de formateo y los cambios de desarrollo
Cómo usar git-clang-format
Instalación
git-clang-format se incluye junto con el paquete clang-format-node. Puede usarse instalando el paquete npm clang-format-git.
Flujo de trabajo básico
- Escribe el código.
- Agrega los cambios al staging (
git add). - Ejecuta
git-clang-format.
Ejemplo
# Agregar nuevo archivo y hacer staging de los cambios
$ git diff --staged
diff --git a/x.cpp b/x.cpp
new file mode 100644
index 0000000..af14ed5
--- /dev/null
+++ b/x.cpp
@@ -0,0 +1,3 @@
+int main() {
+
+}
# Ejecutar git-clang-format
$ git-clang-format
changed files:
x.cpp
# Verificar el estado después del formateo
$ git status
On branch master
Changes to be committed:
new file: x.cpp
Changes not staged for commit:
modified: x.cpp
Con este flujo de trabajo, puedes revisar de forma independiente los cambios de formateo y los cambios de desarrollo. Si no te convence el cambio de formateo, también puedes revertirlo con git checkout.
Especificar estilo
Puedes establecer el estilo de formateo con la opción --style.
$ git-clang-format --style=WebKit
$ git-clang-format --style=file # usar el archivo `.clang-format`
Conclusión
clang-format es una herramienta potente, pero en el trabajo real muchas veces no basta con el simple comando clang-format -i. Si usas git-clang-format, que aplica formateo solo en las partes modificadas, puedes gestionar el código de forma eficiente y simplificar el proceso de revisión.
Como git-clang-format solo formatea los cambios, permite mantener una base de código limpia y profesional al mismo tiempo que ofrece un entorno de desarrollo flexible. Si agregas algunos comandos de Git adicionales al formatear commits de trabajo o ramas completas, puedes resolver fácilmente los problemas de formateo.
¡Gracias por leer este texto tan largo! Les deseo un muy feliz Año Nuevo a todos los lectores de GeekNews 🙇♂️
- Repositorio de GitHub: https://github.com/lumirlumir/npm-clang-format-node
- Sitio oficial de documentación: https://clang-format-node.lumir.page/
2 comentarios
Les doy mi pulgar arriba y me voy
¡¡Gracias!!