[erledigt] Lazarus Dokumentation

[juelin]

Hallo Lazarus Gemeinde,
wir waren ja gestern auf dem Treffen in Bakcknang.
Dort war Dokumentation und Programmgestaltung auch ein großes Thema.
Ich habe mir natürlich auch ein paar Gedanken dazu gemacht.
Zum Thrma Programmgestaltung möchte ich hier nicht näher drauf eingehen.
Ich gebe Euch nur einen Link und jeder muss sehen was er daraus macht.
https://chriswigit.github.io/dev-guidelines/

Zum Thema Dokumentation werde ich in Zukunft folgender Massen vorgehen.
Am Anfang vom Programm (so nach Unit) habe ich folgenden Text eingefügt.

{
Hersteller:
LinSoft Jürgen linder (juelin) dg5uap@darc.de
Lizens:
Opensource entsprechend
Hardware:
keine zusätzliche Hardware
Software:
Folgende Files
ProgDiag.exe muß im Soucepfad vorhanden sein
wie Compelieren:
Lazarus IDE mit FPC
Printer4Lazarus muss im Objektinspektor als neue
Anforderung hinzugefügt sein
wie Ausführen:
Ausführen ProgDiag.exe (Icon)
Benötigte Packages
LCL, LCLBase
}

Wo die Procedure und Funktion deklariert werden (hinter type) mache ich
zu JEDEM Eintrag einen kleinen Kommentar mit //

function Blankdazu(Pos, Lan: integer; var Htextstring: string): string; // Blanks im Htextstring einfügen und in Result zurück geben
// Lan = Ausgabelänge von Result
// Pos 1 = vor dem Text
// Pos 2 = hinter dem Text
procedure AnzeigeLoe; // Löschen alle Ein- und Ausgabefelder der Bildschirmanzeige
procedure LadenVariable; // Laden Tabelle varname ins Stringgrid

Beri den globalen Variablen (hinter Var) mache ich bei JEDER Variable
einen kleinen Kommentar mit //

drucker: string; // Druckername
druckn: integer; // Druckernummer für Tabelle
px: integer; // X aktuell in Pixel
py: integer; // Y aktuell in Pixel
vpx: integer; // X-Differenz in Pixel
vpy: integer; // Y-Differenz in Pixel
format: TPrinterOrientation; // Druckerformat
seite: integer; // Seitenanzahl Drucker
zeile: integer; // Zeilenanzahl Drucker

Im Teil wo die Proceduren mit Inhalt (Befehlen) gefült werden mache ich bei JEDER
Procedure oder Function folgende Überschrift.

Code: Alles auswählen

{
-------------------------------------------------------------------------------------
Funktion: Blannkdazu
          Ändert die Länge eines Strings und gibt den String
          zurück.
          Wenn die Länge des Eingabestrings HTextstring
          kleiner des Wertes in Eingabevariable Lan ist
          wird mit Blanks aufgefüllt.
          Und zwar wenn Eingabevariable Pos = 1 ist
          vor dem Inhalt von Eingabestring Htextstring ansosten
          hinter dem Inhalt von Eingabestring Htextstring.
          Wenn die Länge des Eingabestrings HTextstring
          gleich des Wertes in Eingabevariable Lan ist
          passiert nichts.
          Wenn die Länge des Eingabestrings HTextstring
          größer des Wertes in Eingabevariable Lan ist
          wird der Eingabestring Htextstring verkürzt
          zurück gegeben.
          Und zwar wenn Eingabevariable Pos = 1 ist
          dann wird vorne abgeschnitten ansonsten hinten.
-------------------------------------------------------------------------------------
          Eingabevariablen
		Pos Typ integer
			gibt die Richtung an. Werte (1 oder 1)
		Lan Typ integer
			gibt die maximale Länge des Ausgabestrings
			an.
          Ausgabevariablen
		Rückgabewert mit Result Typ string
                gibt den bearbeiten String Htextstring
                zurück.
-------------------------------------------------------------------------------------
}

function TForm1.Blankdazu(Pos, Lan: integer; var Htextstring: string): string;
  var laenge: integer;
  var stelle: integer;
  var ausgabe: string;
begin
  laenge:=Length(Htextstring);
  ausgabe:=Htextstring;
  if laenge < Lan then
  begin
    while laenge < Lan do
    begin
      if Pos = 1 then
      begin
        ausgabe:=' '+ausgabe;
      end else begin
        ausgabe:=ausgabe+' ';
      end;
      laenge:=Length(ausgabe);
    end;
  end else begin
    if laenge > Lan then
    begin
      if Pos = 1 then
      begin
        stelle:=laenge-Lan+1;
        ausgabe:=Copy(Htextstring,stelle,Lan);
      end else begin
        ausgabe:=Copy(Htextstring,1,Lan);
      end;
    end;
  end;
  Result:=ausgabe;
end;

So das ist mein Vorschlag.
Macht Euch selber Gedanken zu diesem Thema.
Ich weiß, es ist lästig und mach erst einmal unötigen Audwand.
Aber Ihr müsst immer daran denken:
Ihr schreibt jetzt ein Programm (möglichst groß mehrere tausend Zeilen)
und schaut dann nach 10 Jahren mal wider in das Programm.
Wenn keine gute Dokumetation da ist werdet Ihr nicht wissen was da ab geht.

Alles Gute und weiterhin viel Spaß mit Lazarus wünscht
Jürgen

[af0815]

BTW schon mal geschaut wie das im fpc bzw. Lazarus mit der Doku mit Bordmittel funktioniert, bzw. die Header in der fcl bzw. lcl aufgebaut sind ?

Schau die mal fpdoc an. https://wiki.freepascal.org/FPDoc_Editor/de ist bei Lazarus automatisch mit dabei.

[juelin]

Hallo af0815,
ist bestimmt ein tolles Tool.
Gefällt mir aber nicht.
Da keine Infons im Programm anbestimmter Stelle vorhanden sind.
Gruß
Jürgen

[af0815]

Es hängt bei der Vorgangsweise und den Tool von fpc und Lazarus mehr dahinter. Das geht soweit, das automatisiert Dokumentation erstellt werden kann, in sehr vielen Formaten. Wenn man den Objektinspektor ansieht, so sieht man ganz unten auch Hinweise. Auch die Hints im Programmtext die erscheinen hängen von der richtigen Formatierung der Hilfstexte ab. Befolgt man das, so ist die Software auch leichter Dokumentationsfähig.

Eine Alternative bzw. zusätzliches Tool ist auch PasDoc. Das wiederum kann dann das fpdoc xml schreiben, auch damit schliesst sich der Kreis.

Grundlegend, wenn die Dokumentation im Programm zu komplziert ist, ist sie bald veraltet und somit unbrauchbar. Weil dann hat sie denselben Wert wie keine, sogar schlimmer weil si kann einem in die Irre führen. Mann sollte immer KISS (keep it stupid simple) und wenn es geht mit den Tool der Plattform IMHO geschehen.

Ich weis was es heißt Programme (im industriellen Umfeld) zu dokumentieren und bin auch mit meiner alten Dokumentation nach Jahren konfrontiert worden.

Jeder kann machen was er in seinen Programmen will, sobald andere öffentlich Aufgefordert werden es nach einem gewissen Schema zu tun, muß man sich auch der Diskusion stellen.

BTW: Man kann die Diskussion auch auf der Basis weiterführen https://blogs.embarcadero.com/new-delph ... yle-guide/ aber jede Plattform hat ihre eigene Rules.

[h-elsner]

Angeregt von Chris (siehe Link oben) habe ich mir angewöhnt, sprechende Namen zu verwenden. Damit sollten sich weitere Erklärungen möglichst erübrigen.

Beispiel:

Code: Alles auswählen

procedure TForm1.StopAllTimer;
begin
  timerFCHeartbeat.Enabled:=false;
  timerYGCcommandLong.Enabled:=false;
  timerTelemetry.Enabled:=false;
  timerFCCommand.Enabled:=false;
  timerGUI.Enabled:=false;
  timerSensors.Enabled:=false;
  ser:=false;
end;

Das sagt doch alles, oder? Jedenfalls für mich in dem gegebenen Kontext.
Aber zwei Sachen sind als schlechtes Beispiel drin:
TForm1 - ist Mist, geht aber gerade noch so, wenn es nur ein Formular gibt.
ser:=false; - Da weiß ich wahrscheinlich in ein paar Monaten selbst nicht mehr, wozu das da ist. Hier besteht also noch Handlungsbedarf. mal abgesehen davon, dass es in dieser Prozedur sowieso nichts zu suchen hat.

Was klar sein dürfte ist, dass solche Sachen wie Label1 bis Label42 oder so gar nicht gehen.

[Zvoni]

.... und falls das da oben dein "echter" Name und EMail-Adresse ist, solltest du den ersten Post schleunigst "anonymisieren".....

[Warf]

Das problem mit Kommentaren ist, Kommentare können sehr leicht selbst zu bugs werden.
Beispiel, jemand schreibt Code und kommentiert ihn, dann ändert jemand den Code vergisst aber das Kommentar zu updaten, darauf hin benutzt jemand den Code auf Basis des Kommentars was nicht mehr aktuell ist und ein Fehler passiert.

Das Problem bei Kommentaren ist, sie werden nicht vom Compiler geprüft, Bezeichner und Typen schon. Daher ist's besser aussagekräftige Bezeichner und semantisch zugehörige Typen zu verwenden, sodass der code selbsterklärend ist, statt Kommentare

Nehmen wir mal dein Beispiel:

Code: Alles auswählen

drucker: string; // Druckername
// Warum nicht
DruckerName: String;

druckn: integer; // Druckernummer für Tabelle
// Warum nicht
TabellenDruckerNummer: Integer;

px: integer; // X aktuell in Pixel
py: integer; // Y aktuell in Pixel
// Warum nicht
CurrentX, CurrentY: Integer;
// Oder besser
currentPosition: TPoint;

vpx: integer; // X-Differenz in Pixel
vpy: integer; // Y-Differenz in Pixel
// Warum nicht
DeltaX, DeltaY: Integer;
// Oder besser
DeltaPosition: TPoint;

format: TPrinterOrientation; // Druckerformat
// Warum nicht
DruckFormat: TPrinterOrientation;

seite: integer; // Seitenanzahl Drucker
zeile: integer; // Zeilenanzahl Drucker
// Warum nicht
SeitenAnzahl, ZeilenAnzahl: Integer;

Lazarus hat auto complete, du tippst effektiv nicht mehr aber man versteht was was ist ohne kommentare