Was ist der beste Ansatz für Inline-Code-Kommentare?

Wir überarbeiten gerade eine 20 Jahre alte Codebasis und diskutieren mit meinem Kollegen über das Kommentarformat im Code (plsql, java).

Es gibt kein Standardformat für Kommentare, aber in den meisten Fällen machen die Leute im Kommentar so etwas:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

Das vorgeschlagene Format für zukünftige und vergangene Kommentare ist:

// {yyyy-mm-dd}, unique_author_company_id, comment

Mein Kollege sagt, wir brauchen nur den Kommentar und müssen alle vergangenen und zukünftigen Kommentare in dieses Format umformatieren:

// comment

Meine Argumente:

• Ich sage aus Wartungsgründen, es ist wichtig zu wissen, wann und wer eine Änderung vorgenommen hat (auch diese Information steht im SCM).
• Der Code lebt und hat deshalb eine Geschichte.
• Denn ohne die Änderungsdaten ist es unmöglich zu wissen, wann eine Änderung vorgenommen wurde, ohne das SCM-Tool zu öffnen und in der langen Objekthistorie zu suchen.
• weil der autor sehr wichtig ist, ist ein autorenwechsel glaubwürdiger als ein autorenwechsel
• Beweglichkeitsgründe, keine Notwendigkeit zum Öffnen und Navigieren durch das SCM-Tool
• Menschen hätten mehr Angst, etwas zu ändern, was vor 15 Jahren jemand getan hat, als etwas, das kürzlich geschaffen oder geändert wurde.
• etc.

Argumente meines Kollegen:

• Die Geschichte ist im SCM
• Entwickler dürfen den Verlauf des Codes direkt im Code nicht kennen
• Pakete werden 15.000 Zeilen lang und unstrukturierte Kommentare erschweren das Verständnis dieser Pakete

Was ist Ihrer Meinung nach der beste Ansatz? Oder haben Sie einen besseren Ansatz, um dieses Problem zu lösen?

Allgemeine Kommentare

Ich glaube fest daran, dass Kommentare das Warum (nicht das Wie) betreffen . Wenn Sie anfangen, Kommentare darüber hinzuzufügen, wie Sie in das Problem geraten, werden diese Kommentare in Bezug auf den Code durch nichts erzwungen (das Warum ändert sich normalerweise nicht (die Warum-Erklärung kann im Laufe der Zeit erweitert werden)).

In gleicher Weise bringt Ihnen date / authorInfo nichts darüber, warum der Code auf diese Weise erstellt wurde. Genau wie das, wie es im Laufe der Zeit degenerieren kann, weil es keine Durchsetzung durch irgendwelche Werkzeuge gibt. Dieselben Informationen sind auch bereits im Versionsverwaltungssystem gespeichert (sodass Sie den Aufwand duplizieren (jedoch auf weniger zuverlässige Weise)).

Gehen Sie die Argumente durch:

Ich sage aus Wartungsgründen, es ist wichtig zu wissen, wann und wer eine Änderung vorgenommen hat (auch diese Information steht im SCM).

Warum. Keines dieser Dinge scheint mir für die Pflege des Codes so wichtig zu sein. Wenn Sie mit dem Autor sprechen müssen, ist es relativ einfach, diese Informationen aus der Quellcodeverwaltung zu finden.

Der Code hat Leben, aus diesem Grund hatte eine Geschichte.

Der Verlauf wird in der Quellcodeverwaltung gespeichert.
Vertrauen Sie auch, dass der Kommentar von dieser Person verfasst wurde? HowKommentare neigen dazu, sich mit der Zeit zu verschlechtern, so dass diese Art von Geschichte unzuverlässig wird. Versionskontrollsysteme hingegen führen einen sehr genauen Verlauf und Sie können genau sehen, wann Kommentare hinzugefügt / entfernt wurden.

Denn ohne das Änderungsdatum ist es unmöglich zu wissen, wann eine Änderung vorgenommen wurde, ohne das SCM-Tool zu öffnen und in der langen Objekthistorie zu suchen.

Wenn Sie den Daten in einem Kommentar vertrauen.
Eines der Probleme bei dieser Art von Dingen ist, dass die Kommentare in Bezug auf den Code falsch werden. Zurück zum richtigen Werkzeug für den Job. Das Quellcodeverwaltungssystem wird dies korrekt ausführen, ohne dass der Benutzer eingreifen muss. Wenn Ihr Quellcodeverwaltungssystem ein Problem ist, müssen Sie möglicherweise lernen, wie es angemessener verwendet wird (da diese Funktionalität normalerweise einfach ist), oder wenn dies nicht unterstützt wird, ein besseres Quellcodeverwaltungssystem finden.

Da der Autor sehr wichtig ist, ist eine Änderung von authorx glaubwürdiger als eine Änderung von authorhory

Alle Autoren (außer Ihnen) sind gleichermaßen glaubwürdig.

Beweglichkeitsgründe, keine Notwendigkeit zum Öffnen und Navigieren des SCM-Tools

Wenn Ihr Quellcodeverwaltungs-Tool so lästig ist, dass Sie es nicht richtig verwenden, oder (mit größerer Wahrscheinlichkeit), verwenden Sie die falschen Tools, um auf das Quellcodeverwaltungssystem zuzugreifen.

Die Leute hätten Angst, etwas zu ändern, was jemand vor 15 Jahren getan hat, als etwas, das wiederholt hergestellt wurde ...

Wenn der Code 15 Jahre gedauert hat, ist die Wahrscheinlichkeit größer, dass er solider ist als der Code, der nur 6 Monate gedauert hat, ohne dass eine Überprüfung erforderlich ist. Stabiler Code bleibt in der Regel stabil, fehlerhafter Code wird mit der Zeit immer komplexer (da das Problem nicht so einfach ist, wie zunächst angenommen).

Noch mehr Gründe, die Quellcodeverwaltung zu verwenden, um Informationen abzurufen.

Die Geschichte ist im SCM

Ja. Bester Grund noch.

Entwickler dürfen den Verlauf des Codes direkt im Code nicht kennen

Wenn ich diese Informationen wirklich brauche, werde ich sie in der Quellcodeverwaltung nachschlagen.
Ansonsten ist es nicht relevant.

Pakete werden 15.000 Zeilen lang und unstrukturierte Kommentare sind für diese Pakete schwieriger zu verstehen

Kommentare sollten eine Beschreibung dessen sein, warum Sie sowieso etwas tun.
Kommentare sollten NICHT beschreiben, wie der Code funktioniert (es sei denn, der Algorithmus ist nicht offensichtlich).

Ich unterstütze nachdrücklich Ihren Kollegen. Sie werden ohnehin nicht ohne einen Blick auf den SCM auskommen, wenn Sie verstehen möchten, warum etwas geändert wurde, es sei denn, Sie behalten den alten Code in einem Kommentar.

Wenn der Code zu komplex ist, um verstanden zu werden, ohne tonnenweise Kommentare zu schreiben, würde ich vorschlagen, dass Sie Energie in das Refactoring investieren, um den Code ohne tonnenweise Kommentare lesbar / wartbar zu machen.

Schließlich stellen Sie Programmierer ein, keine Geschichtenerzähler ;-)