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).