Eure favorisierte Form der Dokumentation

[Valle]

Wir verwenden Python, daher bin ich hier vielleicht etwas außenvor.

Python unterstützt Dokumentation als Teil der Sprache. Packages, Klassen und Methoden können jeweils mit einem String beginnen, der die Dokumentation beinhaltet. Es existieren entsprechende Tools um das dann in beliebige andere Dateiformate umzuwandeln. Bei uns klappt das eigentlich ganz gut.

Hier mal ein Beispiel, für die, die sowas noch nicht gesehen haben:

Code:

"""
My Module

>>> inline_code_example()
"""
 
class Foo:
    """
    My Class
    """
 
    def __init__(self):
        """
        My Constructor
        """
        pass
 
    def add(self, a, b):
        """
        Returns ``a`` + ``b``
        """
        return a + b

[bernau]

Zur Dokumentation des Quellcodes habe ich ja schon etwas geschrieben.

Dokumentation ist aber ein weit gefächtertes Thema. Zur Dokumentation gehört auch Pflichtenheft, Bedienungsanleitung, etc.

Mit Word-Dateien konnte ich nie wirklich etwas anfangen. Zumal die Arbeit immer an einer Person hängen bleibt.

Wir sind bei diesen Bereichen nun auf ein WIKI umgeschwengt. Zwar bleibt die Doku weiterhin die Aufgabe von 1-2 Personen. Aber Korrekturen (z.B. für die Rechtschreibung und Formulierung) können auf viele Personen aufgeteilt werden. Die Verwaltung des Dokumentes ist zentral. Es gibt keine verschiedenen Versionen. Bei Fragen kann man direkt auf den entsprechenden Link verweisen. Änderungen in der Doku sind leicht auffindbar.

Gute Erfahrung habe ich mit DokuWiki gemacht.

[p80286]

[/OT]
Dokumentation?

Die Form ist mir inzwischen ....egal. Aber stimmen muß sie. Oft genug steht da drin, was man gerne hätte, aber nicht was man programmiert hat.
(Sonst gäb es z.B. keine abweichenden Feldnamen)

Gruß
K-H

[/OT]

[Mavarik]

Zitat von Dejan Vu:

@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

Doch habe ich...

Zitat von Dejan Vu:

Nur frage ich mich, was das für einen Mehrwert hat. Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

Ich kann nicht bei jeder Änderung es in der History nachschauen ob oder was sich da mal geändert hat...

Und ganz besonders, wenn etwas nicht funktioniert, möchte ich die versuche in Quelltext haben, damit ich nicht nach 2 Jahres nochmal das gleiche versuche was vorher schon nicht funktioniert hat.

Ganz besonders wichtig ist das wenn der Source an dieser Stelle auf den 1. Blick falsch erscheint... Dann ist ganz wichtig zu sehen warum? usw...

[mikhal]

Ist schon interessant, dass niemand Delphi Doc oder PasDoc genannt hat. Ich weiß, dass diese Projekte irgendwie alt sind und wohl nicht mehr wirklich weiterentwickelt werden, aber ich habe zumindest Delphi Doc in der Vergangenheit eingesetzt und war vom Ergebnis zufrieden.

Grüße
Mikhal

[TheMiller]

Zitat von mikhal:

Ist schon interessant, dass niemand Delphi Doc oder PasDoc genannt hat. Ich weiß, dass diese Projekte irgendwie alt sind und wohl nicht mehr wirklich weiterentwickelt werden, aber ich habe zumindest Delphi Doc in der Vergangenheit eingesetzt und war vom Ergebnis zufrieden.

Grüße
Mikhal

Ich wollte es auch gerade schreiben. Gerade in Zusammenhang mit Doxygen war ich immer sehr zufrieden. Es werden sowohl Web-Quelltexte, also auch "Hochsprachen" dokumentiert, als HTML-/PDF ausgegeben und mit Links interaktiv versehen!

[Dejan Vu]

Zitat von Mavarik:

Ich kann nicht bei jeder Änderung es in der History nachschauen ob oder was sich da mal geändert hat...

Und ganz besonders, wenn etwas nicht funktioniert, möchte ich die versuche in Quelltext haben, damit ich nicht nach 2 Jahres nochmal das gleiche versuche was vorher schon nicht funktioniert hat.

Ah.. Wir haben Unittests, da stellst sich die Frage nicht, ob irgendwer schon einmal etwas versucht hat. Weil, es funzt jetzt ja

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal), da wäre mir das auch ganz recht gewesen, zu wissen, was ich vorher schon einmal probiert habe.

[bernau]

Zitat von Dejan Vu:

Ah.. Wir haben Unittests, da stellst sich die Frage nicht, ob irgendwer schon einmal etwas versucht hat. Weil, es funzt jetzt ja

Du kannst also alle Programmbereiche mit Unittest kontrollieren und testen? Respekt.

Zitat von Dejan Vu:

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal), da wäre mir das auch ganz recht gewesen, zu wissen, was ich vorher schon einmal probiert habe.

Der Zusammenhang mit der One-Man-Show erschliesst sich mir nicht so ganz. Wenn ich alleine am Projekt arbeite, ist es gut zu wissen, was ich vorher schon mal programmiert habe. Wenn ich mit mehreren an einem Projekt arbeitet, dann muss ich das nicht mehr wissen. Aha? So, so! Sehr aussergewöhnliche Logik.

[Mavarik]

Zitat von Dejan Vu:

Aber als ich selbst eine One-Man-Show war (ich unterstelle Dir das einfach mal)

Da liegst Du falsch... Abgesehen davon möchte ich sehen wie Du einen Canvas 2 PDF Druck mit transparenter Overlay-Grafik in einen Unittest abkasperst...

90% Der Fehler die nach 30 Jahren in einer Software immer noch drin sind... Kannst Du mit Unittests überhaupt nicht erfassen

[Dejan Vu]

Zitat von Mavarik:

Abgesehen davon möchte ich sehen wie Du einen Canvas 2 PDF Druck mit transparenter Overlay-Grafik in einen Unittest abkasperst...

Wenn Du das wirklich sehen willst: Mein Tagessatz außerhalb Berlins beträgt 850 Euro zuzüglich Spesen...

Du hast 30 Jahre alte SW und wir haben von Anfang an mit UT gearbeitet und können daher auch transparentes Hinterwutzrendering mit zwiegenopptem Tretoverlay an Shayderman-Splines kontradisoziieren (und zwar die mit der 3.Ableitung), ohne mit der Wimper zu zucken. Und zwar freihändig. Mit 100% Code Coverage. Mach DAS mal nach.

Mann. Canvas nach PDF. Transparente Overlaytechnik. Pah! Sowas machen wir als als Kata vor dem Daily Scrum. Vor! dem Frühstück. Als Einstieg. Für unsere Vertretungsassistenz.

So.

Übrigens: Man kann so ziemlich alles testen. Kommt nur aufs Mocking Framework an. Aber bei Delphi sind einem da wirklich die Hände gebunden.

Aber zurück zum Thema. Einverstanden?