Erstellen eines Kodierungsstandards-Dokuments

Ich arbeite in einer Firma für Steuerungssysteme, deren Hauptaufgaben SCADA und PLC sind , zusammen mit anderen Steuerungssystemen.

Software-Entwicklung ist nicht wirklich etwas, was das Unternehmen tut, abgesehen von Kleinigkeiten hier und da, bis die Entscheidung getroffen wurde, ein internes Projektmanagement- und Bewertungssystem einzurichten.

Dieses Projekt wurde von Leuten übernommen, die ursprünglich als Software-Leute hierher kamen, und wir sind größtenteils Junioren.

Das Projekt begann klein, also haben wir nur Dinge wie Design, Datenbank etc. dokumentiert, aber wir haben uns nie wirklich auf ein Codierungsformat / Konventionen geeinigt.

Wir haben angefangen, StyleCop zu verwenden, um sicherzustellen, dass wir gut dokumentierten Code haben. Ich bin jedoch der Meinung, dass wir ein offizielles Dokument für die Kodierung von Konventionen / Praktiken benötigen, damit wir einen guten Standard beibehalten können und falls es in Zukunft noch größere Entwicklungsarbeiten gibt, wer auch immer daran arbeitet hat eine gute Grundplatte.

Darin liegt das Problem, ich habe keine Ahnung, wie man ein Dokument für Kodierungskonventionen und -standards erstellt. Ich kann mir nur Beispiele für gute oder schlechte Praktiken vorstellen (z. B. Kamelfall beim Benennen von Variablen, Vermeiden der ungarischen Notation usw.), die wir alle sind kompetent genug Programmierer (anscheinend), aber wir haben einfach keine Charta für solche Sachen.

Um es kurz zu machen, meine Frage lautet: Was sind die wichtigsten Aspekte und Inhalte eines guten Kodierungsstandards-Dokuments?

Was sind die wichtigsten Aspekte und Inhalte eines guten Kodierungsstandards-Dokuments?

1. Wird durch Werkzeuge unterstützt , die von dem Code ermöglichen die automatische Überprüfung . Wenn ich weiß, dass ich mich nicht zur Versionskontrolle verpflichten kann, würde ich ermutigt, diese Regeln in meinem Code zu befolgen. Wenn andererseits ein Programmierkollege irgendwo geschrieben hat, dass ich eine Regel befolgen muss, mache ich keinen Mist über diese Regeln.

2. Seine ausgeklügelter, statt Ihre persönliche Meinung zu sein . Sie sagen nicht einfach: "Ab jetzt verwenden wir keine Regionen mehr, weil ich Regionen nicht mag." Sie würden vielmehr erklären, dass Regionen das Codewachstum fördern und keine größeren Probleme lösen .

   Der Grund ist, dass Ihr Kollege im ersten Fall antwortete: "Nun, ich mag Regionen, also würde ich sie immer noch verwenden." Im zweiten Fall würde dies Menschen, die nicht einverstanden sind, dazu zwingen, konstruktive Kritik, Vorschläge und Argumente zu üben, und Sie letztendlich dazu bringen, Ihre ursprüngliche Meinung zu ändern.

3. Wird gut dokumentiert . Fehlende Dokumentation schafft Verwirrung und Interpretationsspielraum . Verwirrung und Interpretationsmöglichkeit führen zu Stilunterschieden, dh dem, was Standards unterdrücken wollen.

4. Sein weit verbreitet, auch außerhalb Ihres Unternehmens . Ein "Standard", der von zwanzig Programmierern verwendet wird, ist weniger Standard als ein Standard, der Hunderttausenden von Entwicklern auf der ganzen Welt bekannt ist.

Da Sie über StyleCop sprechen, nehme ich an, dass die Anwendung in einer der .NET Framework-Sprachen geschrieben ist.

In diesem Fall halten Sie sich einfach an die Richtlinien von Microsoft, es sei denn, Sie haben schwerwiegende Gründe, etwas anderes zu tun. Es hat mehrere Vorteile, dies zu tun, anstatt eigene Standards zu erstellen. Ausgehend von den vier vorhergehenden Punkten:

1. Sie müssen die StyleCop-Regeln nicht neu schreiben, um sie Ihren eigenen Standards anzupassen. Ich sage nicht, dass es schwierig ist, eigene Regeln zu schreiben, aber wenn Sie dies vermeiden können, bedeutet dies, dass Sie mehr Zeit haben, um etwas Nützliches zu tun.

2. Die Richtlinien von Microsoft sind sehr gut durchdacht. Wenn Sie mit einigen von ihnen nicht einverstanden sind, kann dies daran liegen, dass Sie sie nicht verstehen. Das war genau mein Fall; Als ich mit der C # -Entwicklung anfing, fand ich einige Regeln völlig dumm. Jetzt stimme ich ihnen vollkommen zu, weil ich endlich begriff, warum sie so geschrieben wurden.

3. Die Richtlinien von Microsoft sind gut dokumentiert, sodass Sie keine eigene Dokumentation erstellen müssen.

4. Neue Entwickler, die später in Ihrem Unternehmen eingestellt werden, sind möglicherweise bereits mit den Codierungsstandards von Microsof vertraut. Es besteht die Möglichkeit, dass niemand mit Ihrem internen Codierungsstil vertraut ist.

Als Erstes ist zu beachten, dass es in einem Kodierungsstandarddokument nicht um Richtig und Falsch geht. Es geht nicht um gut und schlecht oder welche Methode besser ist.

Der Zweck eines Kodierungsstandards-Dokuments besteht darin, sicherzustellen, dass der gesamte Code gleich gestaltet, geschrieben und angeordnet ist, damit ein Entwickler leichter von einer Person zur anderen wechseln kann, ohne die erforderliche Mentalität zu ändern, um den Stil einer anderen Person zu lesen.

Es dreht sich alles um Einheitlichkeit und nichts um "Richtig und Falsch"

In Anbetracht dessen sollten Sie in einem Kodierungsstandarddokument Folgendes klarstellen:

Regeln der Namensgebung

Wie werden Sie Ihre Methoden, Variablen, Klassen und Interfaces benennen? Welche Notation verwenden Sie?

Ebenfalls in unseren Standards enthalten war ein abgespaltener Standard für SQL, sodass wir ähnliche Namen für Tabellen, Prozeduren, Spalten, ID-Felder, Trigger usw. hatten.

Vertiefung

Was werden Sie zum Einrücken verwenden? Ein einziger Tab? 3 Leerzeichen?

Layout

Werden geschweifte Klammern in derselben Zeile wie die Öffnungsmethode angezeigt? (in der Regel Java) oder in der nächsten Zeile oder einer eigenen Zeile? (in der Regel C #)

Ausnahmebehandlung / Protokollierung

Was sind Ihre Standards für die Ausnahmebehandlung und -protokollierung, ist alles einheimisch oder verwenden Sie ein Tool von Drittanbietern? Wie soll es angewendet werden?

Kommentieren

Wir haben Standards, um die grammatikalische Korrektheit zu diktieren, und dass Kommentare in der Zeile vor oder nach derselben Zeile beginnen, erhöht die Lesbarkeit. Müssen Kommentare in der gleichen Tiefe wie der Code eingerückt werden? Akzeptieren Sie die Kommentarrahmen, die für größere Texte verwendet werden?

Wie wäre es mit den \\\ on-Methoden für Beschreibungen? Sollen diese verwendet werden? Wann?

Exposition

Sollten alle Ihre Methoden und Felder die niedrigstmögliche Zugriffsebene implementieren?

Auch eine wichtige Sache zu beachten. Ein gutes Standarddokument kann einen großen Beitrag zur Überprüfung von Code leisten. Erfüllt es diese Mindeststandards?

Ich habe kaum die Oberfläche von etwas gekratzt, was in eines dieser Dokumente passen könnte, aber KISS

Mach es nicht lang und langweilig und unmöglich durchzukommen, oder diese Standards werden einfach nicht befolgt, halte es einfach.

Ich habe diesen Prozess mehrmals durchlaufen. Am erfolgreichsten war es jedoch, das Dokument "Coding Standards" eines bekannten Unternehmens zu übernehmen und an Ihre Bedürfnisse anzupassen.

Ich habe zum Beispiel gerade Folgendes gefunden: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Wie auch immer, halten Sie Ihren Flammenwerfer bereit.

Prost,

Ich hasse die meisten Standarddokumente, da sie normalerweise versuchen, die kleinen Dinge ins Schwitzen zu bringen und das Gesamtbild zu ignorieren.

Zum Beispiel sagen fast alle, wie man Variablen benennt oder Klammern setzt. Dies ist ein reiner Stil und trägt wenig dazu bei, eine Gruppe von Entwicklern bei der korrekten Ausführung des Codes zu unterstützen. Sie ignorieren Dinge wie Verzeichnisstruktur und Code-Layout. Ich habe Standarddokumente gesehen, in denen genau angegeben ist, wie viele Leerzeichen zwischen Operatoren und wie viele Leerzeilen zwischen Methoden eingefügt werden müssen. All dies endet in der Regel mit einer Unmenge von Ausnahmen von der Regel, die nur zeigen, wie sinnlos sie wirklich sind, und dann sind sie so groß, dass niemand ihnen folgen kann .

Jetzt benutze ich viele verschiedene Software-Teile von vielen verschiedenen Leuten und sie haben alle unterschiedliche Stile. Ich gewöhne mich einfach daran, ich beklage mich nicht, dass es nicht für alle Entwicklungsgruppen einen gemeinsamen Stil gibt. Solange der Code in einem Projekt ein gemeinsamer Stil ist, ist es mir wirklich egal, was dieser Stil ist. Meine erste Regel für alle Standarddokumente lautet daher: Behalten Sie einen konsistenten Codierungsstil innerhalb des Projekts bei . Niemand sollte eine Feige angeben, wo die Klammern sind, solange sie alle gleich sind. Nimm die Religionskriege und stoße sie :)

Das zweite ist das Code-Layout. Wenn ich ein Stück Code aufgreife, möchte ich sehen, dass es ähnlich aufgebaut ist wie andere, ähnliche Arbeiten. Wenn ich einen Webdienst habe, soll der Name des WSDL-Vertrags eindeutig sein, und der Name der Implementierung soll eindeutig sein. Ich möchte nicht, dass sich jemand ein brandneues und anderes Layout für Dateien und Klassen einfallen lässt. Das heißt, ich muss "Hunt the Code" spielen, was ein Ärgernis ist. Wenn es genauso aussieht wie das letzte Projekt, an dem ich gearbeitet habe, kann ich sofort wissen, wo ich finde, wonach ich suche, und es ist wahrscheinlich die größte Hilfe bei der Arbeit mit dem Code anderer Leute, die ich kenne. Behalten Sie also die Struktur des Code bei (z. B. Dokumentationsordner für Dokumente, Schnittstellen für Schnittstellen usw. - was auch immer für Sie funktioniert, aber bleiben Sie dabei).

Es sollten auch Code-Artefakte vorhanden sein. Sie müssen also angeben, ob es sich bei der erwarteten Fehlerbehandlung um Ausnahmen oder um Fehlercodes handelt. Dokumentarchitekturfunktionen, die verwendet werden . Es sollte auch angegeben werden, welche Art der Protokollierung verwendet werden soll und wie die Protokollierung / Fehlerbehandlung dem Benutzer oder einem beliebigen Subsystem präsentiert werden soll, das zum Verwalten von Code in freier Wildbahn verwendet wird. Ich habe an einem Ort gearbeitet, an dem jedes Projekt anders protokolliert hat - es war erbärmlich, dass jede Codeversion ein eigenes, unterschiedliches Betriebsdokument haben musste, das den Mitarbeitern der Einsatzabteilung mitteilte, wie sie feststellen konnten, ob es schief gelaufen war. Ereignisprotokoll, Protokolldatei (in welchem ​​Fall wo) usw. sind hier gültig. Gleiches gilt für andere allgemeine Aspekte des Codes - wie er konfiguriert wird (es macht keinen Sinn, eine .config-Datei für einige Programme oder eine benutzerdefinierte Datenbank oder Befehlszeilenparameter oder eine Registrierung für andere zu verwenden).

Kurz gesagt, das Einzige, worauf es ankommt, ist Konsistenz . Und da riesige Standarddokumente zu viel sind, um sie zu lesen und auswendig zu lernen, informiere ich die Leute lieber nur über die Dinge, die sie nicht sehen können (z. B. Architekturstandards wie Protokollierung), und fordere sie auf, den Code, den sie schreiben, in Übereinstimmung mit dem zu halten, was gerade vorhanden ist. Und wenn Sie noch keinen Code haben, brauchen Sie kein Standarddokument! (Nun, erst wenn Sie genug geschrieben haben, um es nützlich zu machen).

Nehmen Sie daher die wichtigsten Punkte: Versuchen Sie nicht, ein juristisches Dokument zu erstellen, sondern denken Sie an Dinge, die nicht nur die Codierung betreffen, sondern auch die Funktionsweise des Codes und die Übereinstimmung des Codes mit den Erwartungen anderer. Vertrauen Sie dann den Leuten, die guten Code schreiben, und Sie werden sehen, dass sie es tun. (und wenn sie es nicht tun, können Sie Wörter mit ihnen haben, keine Notwendigkeit, es wie Gesetz niederzulegen).

Tun Sie nicht, es ist eine völlige Verschwendung von Zeit und Energie. StyleCop ist großartig und wurde über Jahre von Leuten gegründet, die viel erfahrener und viel schlauer sind als Sie oder irgendjemand in Ihrem Team. Umarme und liebe es! Es führt Sie kontinuierlich, was besser ist als jedes Dokument, das auf jemanden wartet, der sich die Mühe macht, es zu lesen.