AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren

Eure favorisierte Form der Dokumentation

Ein Thema von Daniel · begonnen am 11. Jul 2015 · letzter Beitrag vom 14. Jul 2015
Antwort Antwort
Seite 3 von 4     123 4   
Benutzerbild von Valle
Valle

Registriert seit: 26. Dez 2005
Ort: Karlsruhe
1.223 Beiträge
 
#21

AW: Eure favorisierte Form der Dokumentation

  Alt 12. Jul 2015, 23:15
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
Valentin Voigt
BOFH excuse #423: „It's not RFC-822 compliant.“
Mein total langweiliger Blog
  Mit Zitat antworten Zitat
Benutzerbild von bernau
bernau

Registriert seit: 1. Dez 2004
Ort: Köln
1.268 Beiträge
 
Delphi 11 Alexandria
 
#22

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 09:42
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.
Gerd
Kölner Delphi Usergroup: http://wiki.delphitreff.de
  Mit Zitat antworten Zitat
Benutzerbild von p80286
p80286

Registriert seit: 28. Apr 2008
Ort: Stolberg (Rhl)
6.659 Beiträge
 
FreePascal / Lazarus
 
#23

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 11:41
[/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]
Programme gehorchen nicht Deinen Absichten sondern Deinen Anweisungen
R.E.D retired error detector
  Mit Zitat antworten Zitat
Benutzerbild von Mavarik
Mavarik

Registriert seit: 9. Feb 2006
Ort: Stolberg (Rhld)
4.123 Beiträge
 
Delphi 10.3 Rio
 
#24

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 12:00
@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...

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...
  Mit Zitat antworten Zitat
Benutzerbild von mikhal
mikhal

Registriert seit: 11. Sep 2003
Ort: Linz am Rhein
795 Beiträge
 
Delphi 11 Alexandria
 
#25

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 12:53
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
Michael Kraemer
Computer erleichtern die Arbeit...
...und die Erde ist eine Scheibe!
  Mit Zitat antworten Zitat
Benutzerbild von TheMiller
TheMiller

Registriert seit: 19. Mai 2003
Ort: Gründau
2.480 Beiträge
 
Delphi XE7 Architect
 
#26

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 16:25
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!
  Mit Zitat antworten Zitat
Dejan Vu
(Gast)

n/a Beiträge
 
#27

AW: Eure favorisierte Form der Dokumentation

  Alt 13. Jul 2015, 22:57
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.
  Mit Zitat antworten Zitat
Benutzerbild von bernau
bernau

Registriert seit: 1. Dez 2004
Ort: Köln
1.268 Beiträge
 
Delphi 11 Alexandria
 
#28

AW: Eure favorisierte Form der Dokumentation

  Alt 14. Jul 2015, 00:34
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.


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.
Gerd
Kölner Delphi Usergroup: http://wiki.delphitreff.de
  Mit Zitat antworten Zitat
Benutzerbild von Mavarik
Mavarik

Registriert seit: 9. Feb 2006
Ort: Stolberg (Rhld)
4.123 Beiträge
 
Delphi 10.3 Rio
 
#29

AW: Eure favorisierte Form der Dokumentation

  Alt 14. Jul 2015, 20:56
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
  Mit Zitat antworten Zitat
Dejan Vu
(Gast)

n/a Beiträge
 
#30

AW: Eure favorisierte Form der Dokumentation

  Alt 14. Jul 2015, 21:33
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?
  Mit Zitat antworten Zitat
Themen-Optionen Thema durchsuchen
Thema durchsuchen:

Erweiterte Suche
Ansicht

Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 13:11 Uhr.
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz