Was sollte in einem Kodierungsstandard sein? [geschlossen]

Was sollte ein guter (gelesen: nützlicher) Codierungsstandard enthalten?

• Dinge, die der Code haben sollte.
• Dinge, die der Code nicht haben sollte.
• Sollte der Codierungsstandard Definitionen von Dingen enthalten, die die Sprache, der Compiler oder der Code-Formatierer erzwingen?
• Was ist mit Metriken wie zyklomatischer Komplexität, Zeilen pro Datei usw.?

Ein Grund für jede Anforderung. Auf diese Weise wird das Befolgen der Norm nicht zu einer Art Frachtkult, und die Leute wissen, dass es in Ordnung ist, die Norm zu ändern, wenn der Grund dafür nicht mehr gilt, oder in bestimmten Fällen, in denen der Grund eindeutig nicht zutrifft, gegen die Norm zu verstoßen .

Tabs vs Spaces! Ich bekomme verrückte Updates, wenn einer meiner Kollegen versehentlich viele Tabs an Leerzeichen festlegt, die in das Repository verschoben werden

Regeln der Namensgebung

EDIT: Damit meine ich Richtlinien benennen, nicht Regeln benennen.

Zum Beispiel wäre eine Richtlinie All boolean values should begin with Is/Can/Has/etc when possible. Eine Regel wäreAll boolean values must start with Is

Ein Codierungsstandard für eine Gruppe sollte die Compileroptionen für Warnungen und Fehler enthalten , die behandelt werden müssen.

Es sollte Programmierern freigestellt sein, die Warnungen für ihren eigenen Code zu erhöhen , es muss jedoch eine Grundvoraussetzung geben, damit das Lesen und Arbeiten mit dem Code eines anderen die Ausgabe des Compilers nicht überfrachtet.

Ein solcher Standard müsste auch festlegen, wie Programmierer solche Warnungen von Fall zu Fall deaktivieren können, falls es einen außergewöhnlichen Code gibt, der ansonsten nicht konform ist.

Einige Standards, die ich mag (ich weiß, dass es viele davon gibt, aber diese sind mir lieber):

• 80% Testabdeckung
• Kollektiver Besitz des Codes (Code schreiben, der von Ihren Teamkollegen gelesen werden soll, nicht vom Compiler)
• Schreiben Sie Kommentare. Schreiben Sie, was Sie einem Neuling sagen würden.
• Halte es einfach

Coding Standards helfen ein wenig, wenn Sie den Code zum ersten Mal schreiben. Sie helfen viel, wenn Sie oder Ihr Nachfolger den Code 2 Jahre später aktualisieren müssen.

Der ideale Standard führt zu Code, mit dem Sie zu jeder beliebigen Seite im Code springen und genau verstehen können, was er beim ersten Durchlesen tut, weil

• Die Namen beschreiben deutlich, welche Daten manipuliert werden.
• die geschweiften Klammern verdeutlichen den Kontrollfluss,
• In den Kommentaren werden nicht offensichtliche Algorithmen usw. erläutert.

Andererseits können zu viele willkürliche Standards den Fluss des Schreibens von Code stören. Daher glaube ich, dass jeder Punkt in einer vorgeschlagenen Kodierungskonvention anhand dieser zwei Kriterien bewertet werden sollte:

• Hilft diese Regel sicherzustellen, dass der Code korrekt ist ?
• Hilft diese Regel sicherzustellen, dass der Code klar ist ?

Wenn beides nicht zutrifft, ist das Element nur willkürlich und wahrscheinlich unnötig

Ich würde die folgenden Dinge in einen Standard aufnehmen, den ich schreibe:

Zur Klarheit:

• Dateiorganisation: Durch die Angabe einer festen Reihenfolge für die Elemente in einer Datei kann das Team problemlos durch andere Dateien navigieren. Sie sollten nicht suchen müssen, um #defines oder Strukturdefinitionen zu finden.

• Namenskonventionen: Konsistente Namenskonventionen tragen zur Lesbarkeit bei. Vermeiden Sie es jedoch, zu viele Regeln zu spezifizieren, da dies die Beschreibbarkeit beeinträchtigt.

• Code-Struktur. Platzierung der geschweiften Klammer, Einrückungsstufen, Leerzeichen gegenüber Tabulatoren usw. Ja, dies kann eine starke persönliche Präferenz sein, aber das Ziel ist klarer Code. Finden Sie die beste Option für das Team und bleiben Sie dabei.

Für die Richtigkeit:

• Best Practices speziell für Ihren Problemtyp: Regeln zur Speicherzuweisung, Parallelität oder Portabilität.

• "Const Correctnesss", bestimmungsgemäße Verwendung von staticund volatileusw.

• Regeln für Präprozessor-Makros und andere leicht missbräuchliche Funktionen der Sprache.

Inspirierende, pragmatische Ideen, die zum Nachdenken anregen, anstatt negative Einschränkungen, die zum Nachdenken anregen.

Ansonsten bekommt man Code-Affen, die Angst haben, die Bananen zu jagen .

Was sollte in einem Kodierungsstandard sein? So wenig wie möglich. Weniger eher mehr. Und mit Recht, bitte.

Nicht weil ich ein Cowboy-Programmierer bin, der keinen Prozess will, sondern weil ich (vermutlich) starke Codierungsspezifikationen gesehen habe, hinter denen keine Logik steckt ein bürokratischer Albtraum, mit dem man arbeiten kann.

Einige Leute scheinen ehrlich zu glauben, dass sie durch Anheben der Standards eine entsprechende Steigerung der Code- "Qualität" sehen und vielleicht auch durch diese Maßnahme. In der Zwischenzeit werden sie Architektur, Leistung, gesunden Menschenverstand und eine Reihe anderer Dinge ignorieren, die am Ende mehr als die Anzahl der Zeilen in einer Datei ausmachen.

Ein Verfahren zur Codeüberprüfung, um den Standard durchzusetzen. Oh, und auch um Bugs zu finden.

Ein guter alter gesunder Menschenverstand würde nicht schaden. Es gibt viel zu viele Standard-Codierungsdokumente, die an irrelevanten Punkten arbeiten (Elemente wie Schriftart und Schriftgröße gehören zu den extremeren, die ich gesehen habe).

Wenn Sie zu einer Gruppe von Entwicklern gehören, sollten Sie miteinander sprechen und sich Ihren Code ansehen, einen Konsens darüber erzielen, was akzeptabel ist, und die wichtigsten Punkte als Richtlinien aufschreiben, diese jedoch beibehalten nur diese Richtlinien. Wenn Sie keine Abweichung von den Richtlinien rechtfertigen können, sollten Sie sich überlegen, warum Sie dies tun.

Am Ende des Tages ist klarer und verständlicher Code wichtiger als jede starre Regel in Bezug auf Layout oder Typografie.

Wie bereits erwähnt, ist die Codetestabdeckung wichtig. Ich sehe auch gerne:

• Projektstruktur. Sind die Tests Teil des Codes oder befinden sie sich in einem separaten Projekt / Paket / Verzeichnis? Entspricht der UI-Code dem Back-End-Material? Wenn nicht, wie ist es unterteilt?

• Entwicklungsprozess. Tests vor Code schreiben? Hat das Reparieren defekter Builds Vorrang vor der Entwicklung? Wann werden Codeüberprüfungen durchgeführt und was sollten sie abdecken?

• Quellcodeverwaltung. Was wird wann eingecheckt? Werden die Designdokumente und Testpläne revisionskontrolliert? Wann verzweigen Sie und wann taggen Sie? Behalten Sie frühere Builds bei und wenn ja, wie viele / wie lange?

• Bereitstellungsstandards. Wie ist ein Build verpackt? Was muss in den Versionshinweisen stehen? Wie werden Upgrade-Skripte erstellt / gesteuert / ausgeführt?

Vergessen Sie den ganzen Mist über Namenskonventionen, Formatierung und die Anzahl der Zeilen in einer Funktion / Methode / einem Modul. Eine Regel: Verwenden Sie den vorhandenen Stil in dem Stil, den Sie gerade bearbeiten. Wenn Sie den Stil von jemandem nicht mögen, wählen Sie ihn in einer Codeüberprüfung aus. Die einzige Ausnahme könnte die Sache zwischen Tabulatoren und Leerzeichen sein, wenn nur viele Editoren / IDEs blindlings eine in die andere konvertieren und Sie dann Ihren Änderungsverlauf zerstören, weil jede Zeile geändert wurde.

Ich denke, es gibt zwei Dinge, die angesprochen werden müssen, und ich würde sie in der Tat getrennt betrachten, da sie nicht auf die gleiche Weise angegangen werden können, obwohl ich beide für wichtig halte.

• Der technische Aspekt: ​​der darauf abzielt, riskanten oder falsch geformten Code zu vermeiden (auch wenn er vom Compiler / Interpreter akzeptiert wird)
• Der Präsentationsaspekt: ​​der sich damit befasst, das Programm den Lesern klar zu machen

Den technischen Aspekt qualifiziere ich als Coding Standard , ebenso wie Herb Sutter und Andrei Alexandrescu mit ihren C ++ Coding Standards . Die Präsentation, die ich für den Coding Style qualifiziere , umfasst Namenskonventionen, Einrückungen usw.

Kodierungsstandard

Ein Kodierungsstandard kann, da er rein technisch ist, größtenteils objektiv sein. Als solche sollte jede Regel durch einen Grund gestützt werden. In dem Buch, auf das ich mich bezog, hat jeder Punkt:

• Ein Titel, einfach und auf den Punkt
• Eine Zusammenfassung, die den Titel erklärt
• Eine Diskussion, die das Problem des Andersseins verdeutlicht und somit die Begründung angibt
• optional Einige Beispiele, denn ein gutes Beispiel sagt mehr als tausend Worte
• optional Eine Liste von Ausnahmen, auf die diese Regel nicht angewendet werden kann, manchmal mit Umgehungen
• Eine Liste von Referenzen (andere Bücher, Websites), die diesen Punkt besprochen haben

Begründung und Ausnahmen sind sehr wichtig, da sie das Warum und Wann zusammenfassen.

Der Titel muss so eindeutig sein, dass man während der Reviews nur eine Liste der Titel (Spickzettel) haben muss, mit denen man arbeiten kann. Und gruppieren Sie die Artikel natürlich nach Kategorien, um sie leichter finden zu können.

Sutter und Alexandrescu haben es geschafft, eine Liste von nur hundert Elementen zu haben, obwohl C ++ als haarig gilt;)

Codierungsstil

Dieser Teil ist im Allgemeinen weniger objektiv (und kann ausgesprochen subjektiv sein). Hier soll die Konsistenz gewährleistet werden, da dies den Betreuern und Neuankömmlingen hilft.

Sie möchten nicht in einen heiligen Krieg eintreten, um welchen Einzug oder Klammerstil es sich hier besser handelt. Dafür gibt es Foren. In dieser Kategorie tun Sie also Dinge durch Konsens> Mehrheitsabstimmung> willkürliche Entscheidung des / der Anführer (s).

Ein Beispiel für die Formatierung finden Sie in der Liste der Optionen von Artistic Style . Idealerweise sollten die Regeln klar und vollständig genug sein, damit ein Programm den Code neu schreiben kann (obwohl es unwahrscheinlich ist, dass Sie jemals einen Code erstellen werden;))

Für die Namenskonvention würde ich versuchen, Klassen / Typen leicht von Variablen / Attributen zu unterscheiden.

Es ist auch in dieser Kategorie, dass ich die "Maßnahmen" wie klassifizieren:

• Bevorzugen Sie kurze bis lange Methoden: Es ist normalerweise schwierig, die Länge zu bestimmen
• Frühes Zurück / Weiter / Pause vorziehen, um Einrückung zu reduzieren

Verschiedenes?

Und als letztes Wort gibt es einen Punkt, der in Coding Standards selten, wenn überhaupt, diskutiert wird, vielleicht weil er für jede Anwendung spezifisch ist: Code-Organisation. Das architektonische Problem ist vielleicht das herausragendste Problem, es geht um das ursprüngliche Design, und Sie werden in Jahren davon geplagt sein. Sie sollten vielleicht einen Abschnitt für die grundlegende Dateibehandlung hinzufügen: öffentliche / private Header, Abhängigkeitsverwaltung, Trennung von Bedenken, Schnittstellen zu anderen Systemen oder Bibliotheken ...

Aber das ist nichts, wenn sie nicht tatsächlich angewendet und durchgesetzt werden .

Jeder Verstoß sollte während der Codeüberprüfung zur Sprache gebracht werden, und keine Codeüberprüfung sollte in Ordnung sein, wenn ein Verstoß vorliegt:

• Korrigieren Sie den Code entsprechend der Regel
• Korrigieren Sie die Regel so, dass der Code nicht mehr auffällt

Eine Regel zu ändern, bedeutet natürlich, dass die Verantwortlichen das "go ahead" machen.

Mir gefällt das Format in den Framework Design Guidelines , das einen allgemeinen Abschnitt und Erläuterungen zu den Richtlinien enthält. Das nützlichste Bit sind die Details, die mit Do, Do Not, Avoid und Consider beginnen.

Hier ist ein Beispiel im Abschnitt Implementieren von Schnittstellenelementen. Es enthält explizit die folgenden Elemente (Anmerkung: Ich habe die Begründungen aus Gründen der Bervität fallen gelassen.)

Vermeiden Sie die explizite Implementierung von Schnittstellenmitgliedern, ohne dass dies unbedingt erforderlich ist

Erwägen Sie die explizite Implementierung von Schnittstellenelementen, wenn die Elemente nur über die Schnittstelle aufgerufen werden sollen.

Verwenden Sie keine expliziten Member als Sicherheitsgrenze.

Stellen Sie ein geschütztes virtuelles Mitglied bereit, das dieselbe Funktionalität wie das explizit implementierte Mitglied bietet, wenn die Funktionalität durch abgeleitete Klassen spezialisiert werden soll.

Dies erzeugt einen guten allgemeinen Ton. Durch die Verwendung von Vermeiden und Überlegen können Sie Entwicklern die Möglichkeit geben, ihr Urteilsvermögen zu nutzen. Auch weil es sich um Richtlinien und nicht um Regeln handelt, finden Entwickler sie wahrscheinlich schmackhafter und folgen ihnen mit höherer Wahrscheinlichkeit.

Niemand scheint die Sicherheit erwähnt zu haben - in einem Codierungsstandard muss auf die Anforderungen an den sicheren Code Bezug genommen werden (z. B. die Verwendung von Eingabevalidierungsmodulen, das Verbieten bekannter schwacher Funktionen wie strcpy, Fehlerbehandlungsanforderungen usw.).

Beispiele. Ordentlich angeordnete, nicht triviale, realitätsnahe Beispiele, die von jeder Regel Gebrauch machen. Kommentare (nicht unbedingt Teil des Codes) Welcher Teil des Beispiels welcher Regel folgt.

Vorlagen. Nicht die Art von C ++, sondern etwas zum Kopieren, Einfügen und Füllen mit Live. Es ist viel einfacher, diesen 24-zeiligen Textkommentar richtig zu machen, wenn Sie einen Verweis zum Kopieren haben.

Hauptmerkmal: Absolut maximal zwei Seiten.

Dies ist etwas, das jeder Entwickler lesen und sich merken soll. Sie sollten nicht jedes Mal im Standard nachschlagen müssen, wenn Sie eine neue Funktion (oder noch schlimmer eine neue Zeile) schreiben müssen. Fassen Sie sich also kurz und halten Sie sich nur an die Regeln, die dem Endprodukt wirklich einen Mehrwert verleihen.

Coding Standards ist wirklich mehrere Elemente:

Kodierungskonventionen

• Diese Dinge brauchen keinen anderen Grund als "Konsistenz der Codebasis" zum Beispiel. '_' in privaten Mitgliedsvariablen verwenden oder nicht.
• Es könnte mehrere richtige Ansätze geben. Müssen Sie nur eine für die Konsistenz auswählen. zum Beispiel. Behandeln von Fehlern mithilfe von Ausnahmen oder Fehlercodes.

Best Practices

• Diese Artikel brauchen immer einen guten Grund mit einigen klaren Beispielen

zum Beispiel. Lassen Sie Catch nach dem Versuch niemals leer

try { Foo(); } catch { //do nothing }

1) Wenn eine von Foo () ausgelöste Ausnahme vorliegt, kann dies zu anderen Problemen bei den folgenden Funktionen führen, die davon ausgehen, dass foo erfolgreich war.

2) Der globale Fehlerbehandler benachrichtigt das Support-Team nicht über Ausnahmefälle, wenn dies auf Anfrage geschieht

• behandelt die Praktiken der "defensiven Codierung", wie die Verwendung von Asserts zum Testen Ihrer Annahmen.

Codierungsumgebung

• Tools, die das gesamte Team verwendet. zum Beispiel. VS 2010, Resharper, Brennofen, etc ..

Auf Papier geschriebene Codierungsstandards sind nur so effektiv. Mir gefällt, wie Go seinen Kodierungsstandard veröffentlicht. Es hat das Werkzeug, gofmtum den Programmtext in ein Format zu formatieren. Jede Debatte über das Codierungsformat wird dann einfach als Patch zu den Quellen von führen gofmt.

Was das Format haben soll,

• wie man Variablen, Makros, Konstanten, Literale, Funktionen usw. benennt
• wie man {,}, (,), [,] setzt, wenn es um ifFunktionskörper, Anweisungsblöcke für andere Zwecke geht,
• wie breit sollen die einrückungen sein,
• Wie viele Zeichen eine Textzeile enthalten darf
• Wie viele Ebenen von Einrückungen sind zulässig, bevor der Code zur Umgestaltung zurückgewiesen / gesendet wird?
• Wie viele Codezeilen pro Funktion zulässig sind, bevor sie zur Umgestaltung zurückgesendet werden
• Maximale Anzahl von Argumenten, die eine Funktion annehmen kann, bevor sie zur Umgestaltung zurückgesendet wird
• Ein paar Zeilen mit Kommentaren, bevor eine Funktion beginnt, kurz zu erklären, was sie tut, wenn der Body eine Seite des Bildschirmcodes überschreiten soll. Überlassen Sie die Erreichung des Ziels dem Code im Funktionskörper

Wenn ich den Code anderer (meistens in C) lese, wenn Variablen- / Funktionsnamen im Kontext des Projekts nicht intuitiv sind oder wenn es mehr als fünf Einrückungsstufen gibt oder wenn Funktionen mehr als sechs oder sieben Argumente benötigen oder eine Funktion für mehr als ausgeführt wird Bei zwei oder drei Seiten auf dem Bildschirm wird es sehr schwierig, den Code zu lesen und zu verstehen. Wenn Sie nach Verbesserungen / Wartungsarbeiten gefragt werden, erhöht dies nur die Schwierigkeit. Ich möchte, gofmtdass ein Programm für jedes Projekt (oder sogar für jede Sprache) geschrieben und jede Quellcodedatei durch dieses Programm ausgeführt wird, bevor sie in das Projekt übernommen wird.

Mir gefällt der Google JavaScript Style Guide .

Die Kurzfassung in den Richtlinien enthält jedoch Details, falls Sie diese benötigen.

Selbstdokumentierender Code (Kommentare, Variablennamen, Funktionsnamen usw.)