Generierung von Kodierrichtlinien aus CheckStyle

Question

Gibt es eine Möglichkeit, ein 'schönes' Coding Conventions / Guidelines Dokument aus einer bestehenden CheckStyle Konfigurationsdatei zu generieren?

Dieses Dokument muss die Beschreibung der durchgesetzten Regeln und die Konfigurationswerte (wie die maximale Zeilenlänge, die Schwere der Verletzung usw.) enthalten.

Der Vorteil eines solchen Dokuments besteht darin, dass ein neues Teammitglied schneller in Betrieb genommen werden kann, ohne die CheckStyle-Konfigurationsdatei lesen zu müssen.

Answer 1

Ich würde generell davon abraten, auch nur Teile eines Kodierrichtlinien-Dokuments zu erstellen, da dies zu Akzeptanzproblemen bei Ihren Softwareingenieuren führen würde. Außerdem sollten die Checkstyle-Regeln meiner bescheidenen Meinung nach nicht Teil des Kodierungsrichtlinien-Dokuments selbst sein. Stattdessen sollte in den Kodierungsrichtlinien etwas stehen wie "Achten Sie darauf, keine Checkstyle-Probleme zu verursachen".

Das Checkstyle-Tool kann mit Informationen konfiguriert werden, die dem Entwickler mit der Warnung angezeigt werden. Auf diese Weise werden die Entwickler nicht brauchen ein externes Dokument zu öffnen, um Checkstyle-Warnungen korrekt zu beheben, da alle erforderlichen Informationen bereits vorhanden sind.

Beispiel: Die LocalVariableName check prüft die Benennungskonvention für nicht-finale lokale Variablen. Der Standardnachrichtentext ist:

Member Names: Name 'Foo' must match pattern '^[a-z][a-zA-Z0-9]{0,31}$'.

Wenn Sie die Prüfung wie folgt konfigurieren:

<module name="LocalVariableName">
  <message key="name.invalidPattern"
    value="Local variable name ''{0}'' must not be longer than 32 alphanumeric
           characters and start with a lowercase letter. Regex: ''{1}''"/>
</module>

Die Ausgabe würde dann lauten:

Local variable name 'Foo' must not be longer than 32 alphanumeric characters and
start with a lowercase letter. Regex: '^[a-z][a-zA-Z0-9]{0,31}$'

Zugegebenermaßen, wenn alle Wenn Ihre Entwickler ihre regulären Ausdrücke gut genug kennen, ist der neue Nachrichtentext nicht notwendig. Aber nicht jeder ist ein Regex-Experte, und dies ist nur ein Beispiel, das sich auf viele Prüfungen anwenden lässt, auch auf Prüfungen ohne Regexe.

Answer 2

Hier sind einige typische Kodierungsstandards aufgeführt:

Comments:
    Write Javadoc comments for all classes, methods, and variables.
Naming conventions:
    Class names should be nouns, in mixed case with the first letter of each internal word capitalized (MyClass).
    Variable names should be nouns, in mixed case with a lowercase first letter, and with the first letter of each internal word in upper case (myVariable).
    Constants should be in all uppercase with words separated by underscore (MY_CONSTANT_VALUE).
Indentation:
    Spaces should be preferred to tabs for indenting purposes.
Declarations:
    One declaration per line, with comments, for example:

    int class; // The child's class, from 1 to 8
    int age;   // The child's age

    rather than:

    int class, age;

Statements:
    Opening braces in compound statements should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement, for example:

    while (i < 10) {
    i++;
    }

Best practices:
    Use the final keyword for variables and parameters that will not need to be modified.
    Don't declare variables within loops