Normdokument

Question

Ich schreibe ein Dokument zu Codierungsstandards für ein Team von etwa 15 Entwicklern mit einer Projektbelastung zwischen 10 und 15 Projekten pro Jahr.Neben anderen Abschnitten (die ich hier posten kann, sobald ich dazu komme) schreibe ich einen Abschnitt über Codeformatierung.Daher halte ich es zunächst für sinnvoll, dass wir, aus welchem ​​Grund auch immer, einige grundlegende, konsistente Codeformatierungs-/Benennungsstandards festlegen.

Ich habe mir etwa zehn Projekte angeschaut, die in den letzten drei Jahren von diesem Team geschrieben wurden, und stelle offensichtlich eine ziemlich große Bandbreite an Stilen fest.Auftragnehmer kommen und gehen und manchmal verdoppelt sich sogar die Teamgröße.

Ich suche nach ein paar Vorschlägen für Codeformatierungs- und Benennungsstandards, die sich wirklich ausgezahlt haben ...aber das kann durchaus auch gerechtfertigt sein.Ich denke, Konsistenz und gemeinsame Muster tragen wesentlich dazu bei, den Code wartbarer zu machen ...Aber gibt es noch andere Dinge, die ich bei der Definition dieser Standards berücksichtigen sollte?

• Wie ordnet man Klammern an?Befolgen Sie beim Umgang mit Klassen, Methoden, Try-Catch-Blöcken, Switch-Anweisungen, If-Else-Blöcken usw. die gleichen Klammerrichtlinien?

• Ordnen Sie Felder in einer Spalte an?Notieren/stellen Sie privaten Variablen einen Unterstrich voran?Befolgen Sie Namenskonventionen, um das Auffinden von Einzelheiten in einer Datei zu erleichtern?Wie ordnen Sie die Mitglieder Ihrer Klasse an?

Was ist mit Vorschlägen für Namespaces, Verpackungen oder Quellcode-Ordner-/Organisationsstandards?Ich neige dazu, mit etwas zu beginnen wie:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

Ich bin gespannt, ob es andere, akzeptiertere Praktiken gibt, als ich es gewohnt bin – bevor ich es wage, diese Standards zu diktieren.Auch Links zu bereits online veröffentlichten Standards wären toll – auch wenn ich davon schon einiges gemacht habe.

Answer 1

Suchen Sie zunächst nach einem automatisierten Codeformatierer, der mit Ihrer Sprache funktioniert.Grund:Was auch immer das Dokument sagt, die Menschen werden unweigerlich gegen die Regeln verstoßen.Es ist viel einfacher, Code durch einen Formatierer laufen zu lassen, als bei einer Codeüberprüfung eine Kleinigkeit zu machen.

Wenn Sie eine Sprache mit einem vorhandenen Standard verwenden (z. B.Java, C#) ist es am einfachsten, es zu verwenden oder zumindest als ersten Entwurf damit zu beginnen.Sun hat sich viele Gedanken über die Formatierungsregeln gemacht;Sie könnten es genauso gut ausnutzen.

Denken Sie auf jeden Fall daran, dass viele Untersuchungen gezeigt haben, dass unterschiedliche Dinge wie die Position von Klammern und die Verwendung von Leerzeichen keinen messbaren Einfluss auf die Produktivität, die Verständlichkeit oder die Häufigkeit von Fehlern haben.Einfach haben beliebig Standard ist der Schlüssel.

Answer 2

Aus der Automobilindustrie kommend, hier ein paar Stilstandards, die aus konkreten Gründen verwendet werden:

Verwenden Sie in Kontrollstrukturen immer geschweifte Klammern und platzieren Sie diese in separaten Zeilen.Dadurch werden Probleme beseitigt, die auftreten können, wenn Personen Code hinzufügen und ihn versehentlich in eine Kontrollstruktur einbinden oder nicht einbinden.

if(...)
{

}

Alle Schalter/Auswahlmöglichkeiten haben ein Standardgehäuse.Im Standardfall wird ein Fehler protokolliert, wenn es sich nicht um einen gültigen Pfad handelt.

Aus dem gleichen Grund wie oben: Any if...elseif...Kontrollstrukturen MÜSSEN mit einem Standard-else enden, das auch einen Fehler protokolliert, wenn es sich nicht um einen gültigen Pfad handelt.Eine einzelne if-Anweisung erfordert dies nicht.

In den gelegentlichen Fällen, in denen eine Schleife oder Kontrollstruktur absichtlich leer ist, wird immer ein Semikolon darin platziert, um anzuzeigen, dass dies beabsichtigt ist.

while(stillwaiting())
{
   ;
}

Benennungsstandards haben sehr unterschiedliche Stile für Typdefinitionen, definierte Konstanten, globale Modulvariablen usw.Variablennamen umfassen den Typ.Sie können sich den Namen ansehen und eine gute Vorstellung davon bekommen, um welches Modul es sich handelt, welchen Umfang und welche Art es hat.Dies erleichtert das Erkennen von typbezogenen Fehlern usw.

Es gibt noch andere, aber diese sind der Hammer für mich.

-Adam

Answer 3

Ich werde Jasons Vorschlag unterstützen.

Ich habe gerade ein Standarddokument für ein Team von 10 bis 12 Personen fertiggestellt, die hauptsächlich in Perl arbeiten.In dem Dokument heißt es, dass "perltidy-ähnliche Einrückungen für komplexe Datenstrukturen" verwendet werden sollen. Wir haben auch jedem Beispiel für Perltidy-Einstellungen zur Verfügung gestellt, die ihren Code bereinigen würden, um diesen Standard zu erfüllen.Es war sehr klar und entsprach weitgehend dem Branchenstandard der Sprache, sodass wir vom Team große Zustimmung dazu gefunden haben.

Als ich mich daran machte, dieses Dokument zu schreiben, habe ich in unserem Repository nach einigen Beispielen für großartigen Code gefragt und ein bisschen gegoogelt, um andere Standarddokumente zu finden, die klügere Architekten als ich sind, um eine Vorlage zu erstellen.Es war schwierig, prägnant und pragmatisch zu sein, ohne in den Bereich der Mikromanager einzudringen, aber es hat sich sehr gelohnt.haben beliebig Standard ist in der Tat der Schlüssel.

Hoffe, es klappt!

Answer 4

Es variiert natürlich je nach Sprache und Technologie.Aufgrund des Aussehens Ihres Beispielnamensraums würde ich auf Java tippen, in diesem Fall http://java.sun.com/docs/codeconv/ ist ein wirklich guter Anfang.Vielleicht möchten Sie sich auch etwas wie die Standardverzeichnisstruktur von Maven ansehen, die dafür sorgt, dass alle Ihre Projekte ähnlich aussehen.