it-swarm.com.de

Erstellen eines Codierungsstandarddokuments

Ich arbeite in einem Unternehmen für Steuerungssysteme, in dem die Hauptarbeit SCADA und PLC ist , zusammen mit anderen Steuerungssystemen Sachen.

Softwareentwicklung ist nicht wirklich etwas, was das Unternehmen tut, abgesehen von kleinen Dingen hier und da, bis die Entscheidung getroffen wurde, ein internes Projektmanagement- und Bewertungssystem zu schaffen.

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

Das Projekt begann klein, daher haben wir nur Dinge wie Design, Datenbank usw. 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, aber ich denke, wir brauchen ein offizielles Dokument für Codierungskonventionen/-praktiken, damit wir einen guten Standard fortsetzen können und wenn es größere Entwicklungsarbeiten gibt Wer auch immer daran arbeitet, hat eine gute Grundplatte.

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

Um es auf den Punkt zu bringen, meine Frage lautet: Was sind die wichtigsten Aspekte und Inhalte eines Dokuments mit guten Codierungsstandards?

15
Felix Weir

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

  1. Unterstützung durch Tools, die eine automatische Überprüfung des Codes ermöglichen . Wenn ich weiß, dass ich mich nicht zur Versionskontrolle von Code verpflichten kann, der einigen Regeln nicht entspricht, wird ich aufgefordert, diese Regeln in meinem Code zu befolgen. Wenn andererseits ein Programmierkollege irgendwo geschrieben hat, dass ich einer Regel folgen muss, mache ich keinen Mist über diese Regeln.

  2. Gut durchdacht sein , anstatt Ihre persönliche Meinung zu sein . Sie sagen nicht einfach: "Von nun an verwenden wir keine Regionen mehr, weil ich Regionen nicht mag." Eher Sie würden erklären, dass Regionen das Code-Wachstum fördern und kein größeres Problem lösen .

    Der Grund ist, dass Ihr Kollege im ersten Fall antworten würde: "Nun, ich mag Regionen, also würde ich sie immer noch verwenden." Im zweiten Fall würde dies andererseits Menschen, die nicht einverstanden sind, zu konstruktiver Kritik, Vorschlägen und Argumenten zwingen und Sie schließlich dazu bringen, Ihre ursprüngliche Meinung zu ändern.

  3. Gut dokumentiert sein . Mangelnde Dokumentation schafft Verwirrung und Interpretationsspielraum ; Verwirrung und Interpretationsmöglichkeit führen zu Stilunterschieden, d. h. den Dingen, die Standards unterdrücken wollen.

  4. Weit verbreitet sein , 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 es sich um StyleCop handelt, ist die Anwendung vermutlich in einer der .NET Framework-Sprachen geschrieben.

In diesem Fall halten Sie sich einfach an die Richtlinien von Microsoft, es sei denn, Sie haben ernsthafte Gründe, etwas anderes zu tun. Dies hat mehrere Vorteile, anstatt eigene Standards zu erstellen. Nehmen Sie die vier vorherigen Punkte:

  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, stattdessen etwas Nützliches zu tun.

  2. Die Richtlinien von Microsoft sind sehr gut durchdacht. Es besteht die Möglichkeit, dass Sie einige von ihnen nicht verstehen, wenn Sie mit ihnen nicht einverstanden sind. Das war genau mein Fall; Als ich mit der C # -Entwicklung begann, fand ich ein paar Regeln völlig dumm. Jetzt stimme ich ihnen vollkommen zu, weil ich endlich verstanden habe, warum sie so geschrieben wurden.

  3. Die Richtlinien von Microsoft sind gut dokumentiert, sodass Sie keine eigene Dokumentation schreiben 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.

24

Als erstes ist zu beachten, dass es in einem Dokument mit Codierungsstandards nicht um richtig und falsch geht. Es geht nicht um gut und schlecht oder welche Methode besser ist.

Der Zweck eines Codierungsstandarddokuments besteht darin, sicherzustellen, dass der gesamte Code gleich entworfen, geschrieben und angeordnet ist, um es einem Entwickler zu erleichtern, von einer Person zur anderen zu wechseln, ohne dass die Mentalität geändert werden muss, um den Stil einer anderen Person zu lesen.

Es geht nur um Einheitlichkeit und nichts um "Richtig und Falsch".

In diesem Sinne sollten Sie in einem Dokument zu Codierungsstandards einige Dinge klarstellen:

Namenskonventionen

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

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

Einrückung

Was werden Sie zum Einrücken verwenden? Eine einzelne Registerkarte? 3 Felder?

Layout

Werden Klammern in derselben Linie wie die Eröffnungsmethode gehalten? (in der Regel Java) oder in der nächsten Zeile oder einer eigenen Zeile? (im Allgemeinen C #)

Ausnahmebehandlung/Protokollierung

Was sind Ihre Standards für die Behandlung und Protokollierung von Ausnahmen? Ist alles aus eigenem Anbau oder verwenden Sie ein Tool eines Drittanbieters? Wie soll es verwendet werden?

Kommentar

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

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

Belichtung

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. Entspricht es diesen Mindeststandards?

Ich habe kaum die Oberfläche von dem gekratzt, was in eines dieser Dokumente gelangen kann, aber K.I.S.S.

Machen Sie es nicht lang und langweilig und unmöglich durchzukommen, oder diese Standards werden einfach nicht befolgt, halten Sie es einfach.

8
RhysW

Ich habe diesen Prozess mehrmals durchlaufen. Und der erfolgreichste (wenn auch ohnehin holprige) Ansatz war, das Dokument "Coding Standards" von einem bekannten Unternehmen zu nehmen und es an Ihre Bedürfnisse anzupassen.

Zum Beispiel habe ich gerade dieses gefunden: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Halten Sie auf jeden Fall Ihren Flammenwerfer bereit.

Prost,

6

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 reiner Stil und trägt wenig dazu bei, einer Gruppe von Entwicklercodes richtig zu helfen. Sie ignorieren Dinge wie die Verzeichnisstruktur und das Codelayout. Ich habe Standarddokumente gesehen, in denen genau angegeben ist, wie viele Leerzeichen zwischen Operatoren und wie viele Leerzeilen zwischen Methoden eingefügt werden sollen. All dies führt normalerweise zu einer Menge Ausnahmen von der Regel, die nur zeigen, wie sinnlos sie wirklich sind, und dann sind sie so groß, dass niemand ihnen folgen kann, was wiederum den Punkt verspottet, den sie anstreben .

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

Das zweite ist das Codelayout. Wenn ich einen Code aufgreife, möchte ich sehen, dass er ähnlich aufgebaut ist wie andere, ähnliche Arbeiten. Wenn ich einen Webdienst habe, soll der Name des WSDL-Vertrags klar sein, und der Name der Implementierung soll klar sein. Ich möchte nicht, dass jemand ein brandneues und anderes Layout für Dateien und Klassen entwickelt. 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, den ich kenne. Also, behalten Sie eine Struktur bei, wie der Code aufgebaut ist (z. B. Dokumentationsordner für Dokumente, Schnittstellen für Schnittstellen usw. - was auch immer für Sie funktioniert, aber bleiben Sie dabei).

Code-Artefakte sollten ebenfalls vorhanden sein, daher müssen Sie angeben, ob es sich bei der erwarteten Fehlerbehandlung um Ausnahmen oder Fehlercodes handelt. Dokumentarchitekturfunktionalität, die verwendet wird. Außerdem sollte angegeben werden, welche Art der Protokollierung verwendet werden soll und wie dem Benutzer oder dem Subsystem, das zum Verwalten von Code in freier Wildbahn verwendet wird, Protokolle/Fehlerbehandlung präsentiert werden sollen. Ich habe an einem Ort gearbeitet, an dem jedes Projekt anders protokolliert wurde - es war erbärmlich, wie jede Code-Version ein eigenes, anderes Operationsdokument haben musste, das den Ops-Leuten sagte, wie sie feststellen sollten, ob es schief gelaufen war. Ereignisprotokoll, Protokolldatei (in welchem ​​Fall wo) usw. sind hier alle gültig. Gleiches gilt für andere allgemeine Aspekte des Codes - wie man ihn konfiguriert (es macht keinen Sinn, für einige Programme eine .config-Datei oder für andere eine benutzerdefinierte Datenbank oder Befehlszeilenparameter oder eine Registrierung zu verwenden).

Kurz gesagt, das einzige, was zählt, 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, mit dem aktuell vorhandenen Code in Einklang zu bringen. 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 also die wichtigsten Punkte: versuchen Sie nicht, ein juristisches Dokument zu erstellen Denken Sie an Dinge, die nicht nur das Codieren betreffen, sondern auch, wie der Code funktioniert und wie der Code den Erwartungen anderer entspricht. Dann vertraue darauf, dass die Leute guten Code machen, und du wirst 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).

4
gbjbaanb

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 weiter, was besser ist als jedes Dokument, das auf jemanden wartet, der sich die Mühe macht, es zu lesen.

2
Martin Maat