Ich habe einen C-, C++-, Java- und JavaScript-Formatter für Node.js mit Clang entwickelt.
(github.com/lumirlumir)- GitHub-Repository: https://github.com/lumirlumir/npm-clang-format-node
- Offizielle Dokumentationsseite: https://clang-format-node.lumir.page/
Hallo!
Ich habe einen Formatter für C, C++, Java und JavaScript entwickelt, der Clang in einer Node.js-Umgebung nutzt. Dieses Projekt ist ein Neuanfang auf Basis des nicht mehr gewarteten clang-format-Pakets von Angular.
Vor zwei bis drei Monaten hatte ich bereits etwas Ähnliches geteilt. Jetzt habe ich die Version v1.3.0 veröffentlicht und zusätzlich eine ausführliche Dokumentationsseite ergänzt, damit Nutzer das Paket noch einfacher und komfortabler verwenden können. Die Dokumentationsseite findet ihr hier. Sie enthält verschiedene Informationen – von der grundlegenden Installation bis zu den Gründen, warum man dieses Paket verwenden sollte. Wer Interesse hat, kann gerne vorbeischauen.
In diesem Update wurden mehrere Tests hinzugefügt, um die Stabilität des Pakets weiter zu erhöhen, und es kamen auch neue Funktionen hinzu.
Dieses Paket steht vollständig unter der MIT-Lizenz und kann frei verwendet werden.
Was ist clang-format-node für ein Projekt?
Dieses Paket ist ein Node.js-Paket auf Basis von Clangs clang-format, das Code-Formatierung für die Sprachen C, C++ und Java unterstützt. Einfach gesagt übernimmt es in einer Node.js-Umgebung eine ähnliche Rolle wie Prettier, unterscheidet sich aber dadurch, dass es Formatierung für C, C++ und Java bietet, die von Prettier nicht unterstützt werden.
Besonders nützlich ist clang-format-node, wenn man – wie bei der Entwicklung von Node.js-Core oder Electron – JavaScript-Code zusammen mit C/C++-Code schreiben muss.
Beim bisherigen clang-format-Paket war es umständlich, zusätzliche Abhängigkeiten installieren zu müssen, die von Betriebssystemumgebungen wie Ubuntu abhängen. Mit diesem Paket kann man dagegen sofort loslegen, ohne zusätzliche Installationen. Außerdem ließ sich das bisherige Paket in CI-Umgebungen nur schwer in Node.js- und npm-basierte Workflows integrieren. clang-format-node kann hingegen einfach per npm installiert und über Skripte konfiguriert werden, was in CI-Umgebungen viele Vorteile bietet.
Welche Eigenschaften hat das Paket clang-format-node?
1. Drop-in Replacement als Ersatz für Angulars clang-format
clang-format-node ist ein Drop-in Replacement, mit dem sich das Paket Angular/clang-format leicht ersetzen lässt.
Der Umstieg vom bestehenden Paket auf clang-format-node ist sehr einfach und ohne komplizierte Schritte sofort möglich.
2. Für die Nutzung von Clang reicht Node.js ohne zusätzliche Abhängigkeiten aus.
Zusätzliche Abhängigkeiten wie Python oder C++ sind überhaupt nicht erforderlich. Mit Node.js allein lässt es sich problemlos ausführen.
3. Breiter Support
Es werden zahlreiche Betriebssysteme und Architekturen sowie Node.js-Versionen, GitHub-Actions-Runner-Images und Docker-Build-Images breit unterstützt.
4. Einfache CI-Konfiguration
Ohne komplizierte Einrichtung kann clang-format-node genauso verwendet werden wie andere Node.js-Pakete.
5. Automatisierte Builds und Releases
Sobald clang-format aktualisiert wird, wird automatisch eine neue npm-Version veröffentlicht. GitHub Actions erkennt Updates regelmäßig, baut das Paket und erstellt anschließend einen Pull Request.
Code formatieren mit clang-format und git-clang-format
(Der folgende Text ist eine teilweise ins Koreanische übersetzte Fassung eines englischen Textes, den ich für den Abschnitt https://clang-format-node.lumir.page/docs/get-started/introduction geschrieben habe.)
Warum Code-Formatierung wichtig ist
Formatiert euren Code immer
Code-Formatierung ist ein sehr wichtiger Schritt zur Verbesserung der Codequalität. Der Kern dabei ist, die Formatierung konsistent zu halten, damit Lesbarkeit und Verständlichkeit steigen.
Was ist clang-format?
clang-format ist ein Tool, das Quelldateien von Sprachen wie C und C++ automatisch formatiert, und wurde als Teil des Open-Source-Projekts LLVM Clang entwickelt.
So funktioniert es
- Konfigurationsdatei erstellen
Es wird eine Konfigurationsdatei (.clang-format) erstellt, die den Formatierungsstil definiert. - Befehl ausführen
Wenn der Befehlclang-formatausgeführt wird, wird der Quellcode automatisch entsprechend den Stilregeln neu formatiert.
Wichtige Merkmale
- Unterstützung vieler Sprachen
Unterstützt werden unter anderem C, C++, Java, JavaScript, Objective-C, Protobuf und C#. - Beispiel für einen Formatierungsbefehl
Wenn man diesen Befehl ausführt, wird die Dateiclang-format -i my_source.cppmy_source.cppautomatisch gemäß dem festgelegten Stil formatiert.
Beispiel für Code-Formatierung
// 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";
}
}
}
Das obige Beispiel zeigt, wie clang-format Code formatiert. Die Formatierungsregeln lassen sich frei an den Stil des Teams anpassen.
Probleme mit clang-format
clang-format ist ein hervorragendes Tool, kann aber Probleme mit bestehendem Code und der Commit-Historie verursachen.
Zentrale Probleme
- Konflikte mit bestehendem Code
Wenn eine ganze Datei formatiert wird, werden auch nicht formatierungsbezogene Bereiche verändert, was unnötige Änderungen verursacht. - Unübersichtliche Commit-Historie
Umfangreiche Formatierungsänderungen machen die Commit-Historie komplexer und können Branch-Merges, Code-Reviews und Code-Analysen erschweren. - Inkonsistenz zwischen neuem und bestehendem Code
Wenn zu bereits formatiertem Code neuer Code hinzugefügt wird, kann es schwierig sein, die Formatierung konsistent zu halten.
Lösung: git-clang-format
git-clang-format ist eine Git-Erweiterung, die dabei hilft, Formatierung nur auf geänderten Code anzuwenden. Dadurch ergeben sich folgende Vorteile:
- Minimierter Formatierungsumfang: Formatierung nur auf geänderten Code anwenden
- Einfachere Reviews: Formatierungsänderungen und Entwicklungsänderungen getrennt prüfen
Verwendung von git-clang-format
Installation
git-clang-format wird zusammen mit dem Paket clang-format-node bereitgestellt. Es kann durch Installation des npm-Pakets clang-format-git verwendet werden.
Grundlegender Workflow
- Code schreiben.
- Änderungen zum Staging hinzufügen (
git add). git-clang-formatausführen.
Beispiel
# Neue Datei hinzufügen und Änderungen stagen
$ 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() {
+
+}
# git-clang-format ausführen
$ git-clang-format
changed files:
x.cpp
# Status nach der Formatierung prüfen
$ git status
On branch master
Changes to be committed:
new file: x.cpp
Changes not staged for commit:
modified: x.cpp
Mit diesem Workflow lassen sich Formatierungsänderungen und Entwicklungsänderungen unabhängig voneinander prüfen. Wenn einem die Formatierungsänderungen nicht gefallen, kann man sie mit git checkout auch wieder rückgängig machen.
Stil festlegen
Mit der Option --style kann der Formatierungsstil festgelegt werden.
$ git-clang-format --style=WebKit
$ git-clang-format --style=file # `.clang-format`-Datei verwenden
Fazit
clang-format ist ein leistungsstarkes Tool, doch in der Praxis reicht der Befehl clang-format -i allein oft nicht aus. Wenn man git-clang-format verwendet, das die Formatierung nur auf geänderte Bereiche anwendet, kann man Code effizient verwalten und den Review-Prozess vereinfachen.
Da git-clang-format nur Änderungen formatiert, lässt sich eine saubere und professionelle Codebasis beibehalten und zugleich eine flexible Entwicklungsumgebung schaffen. Wenn man Arbeits-Commits oder ganze Branches formatieren möchte, lassen sich Formatierungsprobleme mit nur wenigen zusätzlichen Git-Befehlen leicht lösen.
Vielen Dank, dass ihr den langen Text gelesen habt! Ich wünsche allen GeekNews-Leserinnen und -Lesern ein frohes neues Jahr 🙇♂️
- GitHub-Repository: https://github.com/lumirlumir/npm-clang-format-node
- Offizielle Dokumentationsseite: https://clang-format-node.lumir.page/
2 Kommentare
Ich lasse ein Like da.
Vielen Dank!!