Mehrsprachige Quellcode Documentation - Ob & Wie?

[Mavarik]

Hallo Zusammen...

Sourcode Documentation ist ja i.d.R. auf englisch..

Delphi-Quellcode:

   {$REGION 'Documentation'}
   /// <summary>
   ///   Class Information
   /// </summary>
   {$ENDREGION}

Ich stelle mir gerade die Frage, ob es nötig ist, diese auch auf deutsch zu erstellen. Mal abgesehen davon, dass ich kein Tool kenne, welches das sofort machen kann...

Man könnte natürlich externe XML Dateien erzeugen und die dann übersetzen...

Hierbei geht es nicht darum eigene Projekte zu dokumentieren, sondern um eine Sourcecode-Sammlung für andere Developer.

Ist es nötig? Wie haltet Ihr das...?

Mavarik :coder:

[sh17]

Wenn die Hauptsprache deutsch ist, warum nicht einfach deutsch rein schreiben?

[jobo]

Also wenn ich sonst alles erledigt habe, dann denke ich vielleicht mal über Dokumentation in einer 2. Sprache nach. ;)

[TiGü]

Warum willst du sie denn auf deutsch übersetzen?

[Mavarik]

Zitat:

Zitat von TiGü (Beitrag 1324119)

Warum willst du sie denn auf deutsch übersetzen?

Aus dem gleichen Grund warum ME auf den DelphiTagen DavidI immer übersetzt hat.

[p80286]

Zitat:

Zitat von Mavarik (Beitrag 1324108)

Hallo Zusammen...

Sourcode Documentation ist ja i.d.R. auf englisch..

Ist es nötig? Wie haltet Ihr das...?

a)Kommentare? wer liest die?
b)Die sind wie Freitextfelder in Datenbanken, vollkommen überflüssig!

Aber im Ernst welchem Zweck sollen sie dienen?
Meine Kommentare sind während der Entwicklung nur Kauderwelsch und sollte dann irgendwann einmal ein Programmteil halbwegs stabil sein, dann wird das Kauderwelsch durch einen englischen Kommentar ersetzt, damit (beinahe) jeder versteht worum es geht. Wobei Selbstverständlichkeiten nicht dokumentiert werden müssen, aber über das was selbstverständlich ist, hat wohl jeder eine eigene Meinung.

Gruß
K-H

P.S.
Freie Rede und geschriebener Kommentar - da gibt es aber leicht Unterschiede in der Verständlichkeit!

[Mavarik]

Zitat:

Zitat von p80286 (Beitrag 1324136)

a)Kommentare? wer liest die?

Ich habe nicht von Kommentaren gesprochen, sondern von Dokumentation...

Kleines Beispiel aus System.Sysutils

Delphi-Quellcode:

    TMultiWaitEventClass = class of TMultiWaitEvent;
  private
    class procedure FreeAndNil(var Obj); static; inline;
    class function DoWait(const Events: array of TMultiWaitEvent; WaitAll: Boolean; Index: PInteger; Event: PMultiWaitEvent; Timeout: Cardinal): TWaitResult; static;
    function WaiterExpired(var Info: TWaitInfo): Boolean;
    procedure RemoveExpiredWaiters;
  protected class var
    ///  <summary>
    ///    This class variable will be set by a single descendent. The expectation is that one and only one descedent
    ///    of this class exists. That one descendent provides the actual implementation. This class variable is
    ///    used by the static class function Create to construct an instance of that one class that implements the
    ///    needed functionality.
    ///  </summary>
    FMultiEventType: TMultiWaitEventClass;
  protected
    ///  <summary>
    ///    Abstract virtual class overridden in descendant classes to create the proper type for the instance.
    ///  </summary>
    class function CreateInstance: TMultiWaitEvent; virtual; abstract;
    ///  <summary>
    ///    Since This unit doesn't cannot use System.SysUtls, this virtual allows descendants which do have access to
    ///    System.SysUtils to provide a means for this base ancestor class to raise exceptions when validating arguments.
    ///  </summary>
    class procedure ArgumentException; virtual; abstract;
    ///  <summary>
    ///    Since This unit doesn't cannot use System.Classes, this virtual allows descendants which do have access to
    ///    System.Classes to provide a means for this base ancestor to call System.Classes.TThread.GetTickCount.
    ///  </summary>
    class function GetTickCount: Cardinal; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This explicitly locks this specific instance.
    ///  </summary>
    procedure Lock; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This explicitly unlocks this specific instance.
    ///  </summary>
    procedure Unlock; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. This must <strong>atomically</strong> set the state of the event.
    ///  </summary>
    procedure AtomicSetEventState(State: Boolean); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Notifies all current waiters this event is signaled.
    ///  </summary>
    procedure NotifyWaiters; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Clears the storage used for the waiters.
    ///  </summary>
    procedure ClearWaiters; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Add a new waiter to the list of waiters.
    ///  </summary>
    procedure PushWaiter(const Waiter: TWaitInfo); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Removed a waiter from the list of waiters.
    ///  </summary>
    procedure RemoveWaiter(Index: Integer); virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Returns the current number of waiters in the list of waiters.
    ///  </summary>
    function GetWaiterCount: Integer; virtual; abstract;
    ///  <summary>
    ///    Overridden in descendents. Returns the index'th waiter from the waiter list.
    ///  </summary>
    function GetWaiter(Index: Integer): PWaitInfo; virtual; abstract;
    /// <summary>
    ///    Current number of threads waiting on this event.
    /// </summary>
    property WaiterCount: Integer read GetWaiterCount;
    /// <summary>
    ///    Array of PWaitInfo references which contain information about each waiting thread.
    /// </summary>
    property Waiters[Index: Integer]: PWaitInfo read GetWaiter;
  public
    ///  <summary>
    ///    Rather than use a constructor which will create an instance of <strong>this</strong> class, this will
    ///    return an instance of the registered descendent type that provides the actual implementation.
    ///  </summary>
    class function Create: TMultiWaitEvent; static;
    destructor Destroy; override;

    /// <summary>Wait for this event instance to be signaled or Timeout is reached.</summary>
    function WaitFor(Timeout: Cardinal = INFINITE): TWaitResult; virtual; abstract;
    /// <summary>Explicitly set the event as signaled. This procedure is typically called by the implementation of
    ///    a specific IAsyncResult.
    /// </summary>
    procedure SetEvent;
    /// <summary>Explicitly reset the event as unsignaled. This procedure is rarely if ever called. If it is called, it
    ///    is called by the implementation of a specific IAsyncResult.
    /// </summary>
    procedure ResetEvent;

    /// <summary>Wait until all of the indicated TMultiWaitEvents are signaled or Timeout is reached</summary>
    class function WaitForAll(const Events: array of TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached</summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached.
    ///   Index out parameter is set to the index of the TMultiWaitEvent in the provided array which was signaled.
    ///   More than one event may be signaled; Index only indicates which one caused the function to return. Index is undefined if
    ///   Timeout was reached.
    /// </summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; out Index: Integer; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
    /// <summary>Wait until at least one of the indicated TMultiWaitEvents are signaled or Timeout is reached.
    ///    Returns the TMultiWaitEvent instance which was signaled and caused the function to return. Event is
    ///    undefined if Timeout is reached.
    /// </summary>
    class function WaitForAny(const Events: array of TMultiWaitEvent; out Event: TMultiWaitEvent; Timeout: Cardinal = INFINITE): TWaitResult; overload; static;
  end;

Warum macht man die? Damit Du in der IDE sofort die Infos hast.

Oder Schau die Spring4D an... Da ist fast jede Methode beschrieben...

[p80286]

Wer lesen kann ist klar im Vorteil:oops:
Trotzdem bleibt die Frage wer liest's. Besteht die Gefahr, daß Amerikaner oder Franzosen sich daran erfreuen, ist eine deutsche Dokumentation/ deutscher Kommentar nicht sooo toll. Hast Du eine Werkzeugsammlung für den deutschen Markt erstellt, geht Englisch bestimmt, aber der eine oder andere Kunde wird Deutsch dann schon goutieren.
Du hast bestimmt auch schon mal russische Software in die Finger bekommen, mit den Kommentaren/der Dokumentation konnte ich herzlich wenig anfangen .

Gruß
K-H

[Der schöne Günther]

Zitat:

Zitat von Mavarik (Beitrag 1324108)

Hierbei geht es nicht darum eigene Projekte zu dokumentieren, sondern um eine Sourcecode-Sammlung die andere Developer.

Ist es nötig? Wie haltet Ihr das...?

Nix verstehen. Du bekommst Code von einem anderen Team das ihn später wieder zurück bekommt? Ich verstehe das Szenario nicht :|

[Mavarik]

Zitat:

Zitat von Der schöne Günther (Beitrag 1324141)

Zitat:

Zitat von Mavarik (Beitrag 1324108)

Hierbei geht es nicht darum eigene Projekte zu dokumentieren, sondern um eine Sourcecode-Sammlung die für andere Developer.

Nix verstehen. Du bekommst Code von einem anderen Team das ihn später wieder zurück bekommt? Ich verstehe das Szenario nicht :|

für...

Sorry "Schreibfehler".

Wenn ich/wir ein SDK raus gebe... oder genauer FDK... stellt sich mir die Frage ob es nötig ist eine deutsche Übersetzung an zu bieten...

Mavarik

[haentschman]

Moin...8-)

[mein Senf]
Wenn der Quellcode nach extern (Komponenten etc.) geht reicht ein einfaches Englisch aus. Intern bleibts deutsch. Die Übersetzung ist imho überflüssig. Solche Dokumentationsorgien wie in deinem Beispiel (SysUtils) halte ich für übertrieben. Da kann man ja kaum noch Codezeilen finden wenn das in der Implementierung genauso brutal weitergeführt wird.
Ich denke kein Mensch sucht in den Deklarationen nach Informationen zur Verwendung. Ich halte eine "vernünftige" externe Doku wie z.B. http://docwiki.embarcadero.com oder wie z.B. für Komponenten eine Hilfe oder ein PDF für wesentlich eleganter und ausreichend.
:P
[/mein Senf]

[Phoenix]

Zitat:

Zitat von Mavarik (Beitrag 1324143)

Wenn ich/wir ein SDK raus gebe... oder genauer FDK... stellt sich mir die Frage ob es nötig ist eine deutsche Übersetzung an zu bieten...

Meiner Meinung nach ein ganz klares nein.

Und zwar aus folgendem Grund:
Die Basis-Bibliotheken einer jeden gängigen Programmiersprache sind: In englisch.
Auch deren Quellcode-Dokumentation ist: In Englisch.
Nahezu jede erdenkliche Hilfe zu Programmierthemen im Internet findet man mindestens: Auf Englisch.

Ein Software-Entwickler sollte daher des Englischen mindestens readonly ausreichend mächtig sein.

Und falls es einer mal nicht ist, sollte man vielleicht aus den oben genannten Gründen eher darüber nachdenken, die Entwickler vielleicht eher auf einen Fachenglisch-Kurs zu schicken, da man am Ende des Tages vermutlich mehr davon hat, wenn der Entwickler - neben der vermutlich schon existierenden Englischen Doku - auch auf den schier unerschöpflichen Englischen Fachbuch- und Internet-Content zurückgreifen kann als ihm einen nur sehr beschränkten ausschnitt der Problemdomäne mit viel Aufwand ins deutsche zu übersetzen.

Just my 2 cents :)

[Perlsau]

Zitat:

Zitat von Phoenix (Beitrag 1324146)

Ein Software-Entwickler sollte daher des Englischen mindestens readonly ausreichend mächtig sein.

:thumb: Ganz genau, sehe ich auch so: Wenn man schon programmieren will, dann sollte man sich auch die Mühe machen, seine Englischkenntnisse zu verbessern. Ich mache das seit Jahren regelmäßig, so daß ich zumindest einigermaßen gut lesen kann, was in englisch geschrieben steht. Beim gesprochenen Wort hapert es bei mir gewaltig, das liegt wohl am fehlenden Umgang mit englischsprachigen Menschen: Bestimmte Dialekte, insbesondere amerikanische, verstehe ich nur sehr schlecht, und meine Aussprache ist u.a.S. Aber schon damals in den frühen Neunzigern, als ich mit Turbo Pascal begann, erleichterten mir meine Englischkenntnisse den Zugang enorm, sind doch die ausnahmslos in Englisch verfügbaren Befehle, wenn man einmal von allzu kryptischen Bezeichnern absieht, beinahe intuitiv verständlich, wenn man über Grundkenntnisse der englischen Sprache verfügt.

[Dejan Vu]

Also dogmatisch zu verlangen, das Dokumentation immer in Englisch zu erfolgen hat, ist vielleicht etwas kurzsichtig gedacht.

Ich habe für eine deutsche Firma gearbeitet, die Steuerungsprogramme erstellt, die nur dieses Team von Programmierern betreut. Wozu zum Deibel sollten die die Doku in Englisch erstellen, wo doch die wenigsten der Programmierer dieser Sprache so mächtig sind, das sie zusammenhängende Sätze in englisch formulieren können? Deutsch kann jeder, also sind nicht nur Dokumentation, sondern auch sämtliche Bezeichner in Deutsch. Alles andere wäre kreuzdämlich. Natürlich, falls mal ein Schwabe zu den Jungs stößt, hat er ein Problem. :lol:

Derzeit besteht das Team (einer anderen Firma) aus 10 Entwicklern aus 6 Ländern, die eine Legacy Software neu schreibt. Die alte Software enthielt portugiesische Kommentare, portugiesische Bezeichner usw. Natürlich wird *diese* Software in englisch (Quatsch, in C#) geschrieben und dokumentiert.

Es kommt also (wie) immer auf den Kontext an.

[Mavarik]

Zitat:

Zitat von Dejan Vu (Beitrag 1324190)

Ich habe für eine deutsche Firma gearbeitet, die Steuerungsprogramme erstellt, die nur dieses Team von Programmierern betreut. Wozu zum Deibel sollten die die Doku in Englisch erstellen, wo doch die wenigsten der Programmierer dieser Sprache so mächtig sind, das sie zusammenhängende Sätze in englisch formulieren können? Deutsch kann jeder, also sind nicht nur Dokumentation, sondern auch sämtliche Bezeichner in Deutsch. Alles andere wäre kreuzdämlich. Natürlich, falls mal ein Schwabe zu den Jungs stößt, hat er ein Problem. :lol:

...

Es kommt also (wie) immer auf den Kontext an.

Stimmt der Kontext... War der nicht vorgegeben?

Zitat:

Zitat von Mavarik (Beitrag 1324108)

Hierbei geht es nicht darum eigene Projekte zu dokumentieren, sondern um eine Sourcecode-Sammlung für andere Developer.

[DeddyH]

Nö, war er nicht. Geht es um rein deutsch(sprachig)e Developer, oder können die auch irgendwo am Himalaya sitzen? 42!

[Sir Rufo]

Zitat:

Zitat von DeddyH (Beitrag 1324200)

Nö, war er nicht. Geht es um rein deutsch(sprachig)e Developer, oder können die auch irgendwo am Himalaya sitzen? 42!

"andere Developer" war nicht eingeschränkt, somit könnten die sogar auf dem Titan sitzen :stupid:

[Dejan Vu]

Lieber ordentlich in einer Sprache dokumentieren, die man beherrscht, als linkisch, schwer verständlich und teilweise falsch in einer Sprache, die man nicht versteht.

Mein Lieblingsbeispiel war der 'durchlaufende Posten', der von einem Programmierer als 'running Post' betitelt wurde. Ziemlich lustig.

Die Softwaresammlung der Steuerungsprogrammierer (die, die alles in Deutsch gemacht haben), war übrigens für andere Entwickler.

[HeZa]

Hallo Mavarik,

• ihr macht ein SDK und gibt es an Kunden raus
• dir kommt es auf die Dokumentation an, die auch in der IDE zu sehen ist

Dann würde ich die Dokumentation im Quellcode auf jeden Fall nur in English halten. Denn Du kannst nicht wissen, was für Programmierer deine Kunden einsetzen und der Aufwand für eine zweisprachige Version, wäre mir zu hoch.

Wenn ihr davon ausgeht, dass ein sehr hoher Anteil der Programmierer die mit eurem SDK arbeiten Deutsch wesentlich besser versteht als English, würde ich noch eine externe deutsche Dokumentation beilegen.

Und nur im Fall, das Ihr wisst, dass eigentlich nur deutschsprachige Entwickler mit eurem SDK arbeiten und sich das absehbar auch nicht ändern wird, würde ich über eine deutsch Dokumentation im Quellcode nachdenken. Aber das auch nur wenn Kunden bereits eindringlich nach einer deutschen Quellcode Dokumention gefragt hätte.

Wenn es um Aspeckte geht wie, Akzeptanz des SDK im deutschsprachigen Raum, würde ich schauen was die Konkurenz macht (so es denn eine gibt).

[Sir Rufo]

Eine ganz andere Idee wäre eine IDE-Erweiterung, die diese zusätzlichen Informationen bereitstellt.

Die originale Doku ist englisch und über die Erweiterung gibt es die Übersetzung (falls vorhanden).

Bliebe jetzt nur noch die Frage, ob es da ein entsprechendes Interface für die IDE gibt.

Hat da jemand konkrete sachdienliche Hinweise an der Hand?

[Dejan Vu]

@HeZa: :thumb: