Laden...

[Tipp] Schau in die Doku! - Möglichkeiten der Informationsgewinnung

Erstellt von ErfinderDesRades vor 15 Jahren Letzter Beitrag vor 15 Jahren 36.502 Views
ErfinderDesRades Themenstarter:in
5.299 Beiträge seit 2008
vor 15 Jahren
[Tipp] Schau in die Doku! - Möglichkeiten der Informationsgewinnung

"Schau in die Doku!"
:rtfm: ist vermutlich einer der am häufigsten geposteten "Smileys" auf myCSharp. Erfreut den Addressaten üblicherweise aber eher weniger, denn impliziert ja gewissermaßen, dass er seine "Hausaufgaben" nicht gemacht hat.
Nun, diese Hausaufgabe ist nicht so ganz trivial, denn die Doku zum Framework ist gewaltig, wirklich wirklich erschlagend. Und es gibt mehrere Dokus, und tatsächlich finden sich kaum je 2 Programmierer, die dasselbe unter "Doku" verstehen.
Ich versuche mal, Vor- und Nachteile verschiedener Techniken zu listen, die in weitestem Sinne als "Doku" durchgehen könnten. Ist natürlich auch Geschmacksache, aber im Grunde kommt es weniger auf die "Bewertung" an, als darauf, dass sie überhaupt genannt werden, sodass der Leser sich dann sein eigenes Bild machen kann.
Noch eine Vorbemerkung zur MSDN-Offline: Dieses mit dem Visual Studio ausgelieferte Hilfepaket bietet verschiedenerlei Zugänge an:*Kontext-Hilfe *Hilfe-Inhaltsverzeichnis *Hilfe-Index *Hilfe-Suche

Außerdem noch die sehr interessante Artikel-Auswahl "Gewußt wie...".
Außer-Außerdem kann man sich "Hilfe-Favoriten" anlegen.
Leider startet MSDN-Offline ziemlich träge.

So, jetzt aber:
Bewertungen (mehr o. weniger subjektiv)
Die verschiedenen Dokumentationen haben ganz spezifische Stärken und Schwächen. Manche Doku hat so erhebliche Schwächen, dass sie am Rande von "unbrauchbar" steht.
Bestimmte Doku-Formen sind nicht miteinander vergleichbar: Intellisense bearbeitet ein anderes Gebiet, als was man bei Wikipedia herausholen kann, und wieder ein anderes als der ObjectBrowser.*Intellisense:
IMO die genialste Dokumentations-Form überhaupt - so intuitiv und selbsterklärend, dass man gar nicht merkt, wieviel man hier eigentlich lernt. Kann aber (aus Platzgründen) nur Member (inkl. Signatur) und Summary-Dokumentations-Tags anzeigen.
Übrigens nutzt der Programmierer die Intellisense nicht nur, sondern er programmiert sie auch: Ein kluges Design von Klassen und Interfaces führt zu höherwertigen Intellisense-Einträgen für die eigenen "Werke":
• gute Kapselung legt nur wenige Member offen, sodass Intellisense eine prägnante Auswahl anzeigt.
• _:::

*Kontext-Hilfe

  • einfach aufzurufen: Wort anwählen, F1 drücken
  • Die Kontexthilfe funktioniert auch aus dem Fehlermeldungs-Fenster heraus! Einfach Fehlermeldung anwählen, F1 drücken. Die Info ist meist sehr gut, z.T. incl. Codebeispiele, die den Fehler reproduzieren etc.
  • Die Kontexthilfe funktioniert auch aus dem ObjectBrowser heraus! (seit 2010) Einfach im ObjectBrowser einen Eintrag anwählen, und F1 drücken. Damit hat man indirekt eine hinreichende Suchfunktion für die MSDN gewonnen, die, wenn man sie direkt über den Browser bedient, ziemlich unübersichtlich ist. Bisher haben Programmierer ja vorwiegend über Google in der MSDN suchen lassen - also das geht jetzt über den ObjectBrowser wesentlich gezielter.
  • Codebeispiele (wenn man Glück hat)
  • enger Blick: zeigt nur einen (den "besten") Treffer an. Damit sind sowohl Artikel zu grundlegenden Konzepten als auch Alternativ-Ansätze erst mal ausgeblendet

*Hilfe-Index:

  • Ausführlichkeit
  • Codebeispiele
  • Grundlagen-Info, Erläuterung von Konzepten ("Informationen zu ..." - Treffer, "Hinweise" - Abschnitte)
  • praktische Anleitungen ("Gewußt wie ..." - Treffer)
  • weiterer Blick: bietet immer eine Auswahl von Treffern an

*Hilfe-Suche

  • Die Treffer sind nur gelistet. Keine Darstellung im Frameset, mit Navigation- und Content- Frame. Ich weiß nicht, warum ich das verwenden sollte, wenn der Hilfe-Index zur Verfügung steht.

*MSDN Online - englisch oder deutsch

  • aktuell, Referenz-Status
  • bietet keine brauchbare Suchfunktion an. Theoretisch sollte der Document-Explorer der IDE ebensogut Online abfragen, bei mir hat das aber (in bisher 8 verschiedenen Installationen) noch nie funktioniert

*Google, SearchDotNet

  • mit Suchmaschinen "kann man reden!" 😉 Beispiel Google-Suche: "C# treeview prevent node doubleclick". Das hinter dieser Formulierung stehende Schema ist: Sprache - Klasse - Aktion. Wichtig: Englisch "sprechen". Zum Thema gibtes auch einen CodeProject-Artikel mit guten Tipps.
  • einfache Begriffe findet der Hilfe-Index effizienter

*ObjectBrowser

  • schnell
  • prägnant
  • weiter Blick: Indem die Info zum einzelnen Item sehr knapp gehalten ist, können viele Item sehr übersichtlich angezeigt werden.
  • macht den Aufbau des Frameworks transparent
  • einfach aufzurufen - nämlich F2 (alternativ: Menü - Ansicht - ObjektKatalog)
  • in VB kommt er auch kontext-sensitiv, nämlich wenn man für ein Wort im Code das KontextMenü "zur Definition gehen" aufruft

*MetaDaten
Jedes Wort im Code genießt die Unterstützung des KontextMenüs "Zu Definition gehen", woraufhin der Cursor an die Position springt, wo die angefragte Entität deklariert wird. Ist die Deklaration nicht als Code verfügbar (ist z.B. Bestandteil einer eingebundenen Dll), so werden "MetaDaten" generiert - eine Art Code-File, welches alle Member der Klasse listet, incl. Signaturen, Attribute und Dokumentations-Kommentaren

  • einfach aufzurufen
  • einzige "IDE-Built-In"-Möglichkeit, die Attributierung der angefragten Items zu erfahren
  • erbärmliche Darstellung

*Reflector (kostenloses Tool) s.a.: [Artikel] .NET Reflector
die haben inzwischen per automatischen Updates das ehemals kostenlose Tool durch etwas kostenpflichtiges ausgetauscht. Kann man also nicht mehr zu "Doku" zählen 😜
Edit: Seit einiger Zeit nutze ich "IlSpy" - das ist wieder ein kostenloses Tool (zumindest zum Zeitpunkt, als ich das installiert hatte)

*Rosylin
Seit einiger Zeit kann man die Framework-Sources auch Online direkt in Augenschein nehmen - inklusive Such-Funktion: http://referencesource.microsoft.com/

*Framework-Source-Code
Kann man sich herunterladen und installieren. Dann seien die MetaDaten vom Tisch, weil "Zu Definition gehen" bei installierten Framework-Sources eben genau dieses tut. Auch dem fabelhaften Reflector wäre damit ein großer Teil seines Wassers abgegraben (ich hab jedenfalls bisher nie was anderes als Framework-Sources disassembliert).
(neues Wissen gleich angewendet) - nach ".net download framework sources" googeln - Tatsache! - findet diesen Blog: Configuring Visual Studio to Debug .NET Framework Source Code
Leider muß man dort lesen: "Note this functionality is not available on the Express versions of the Visual Studio 2008 products.".
Mit dem NetMassDownloader kann man die Source auch runterladen, aber die Präsentation bleibt wohl trotzdem hinter der höherwertiger VS-Editions zurück ("Zu Definition gehen", Debugger-Einzelschritt-Unterstützung).

*Wikipedia

  • sprach-unabhängiges Grundlagen-Wissen, Design-Patterns, prinzipieller Aufbau von Datenstrukturen, Algorithmen, mathematische Grundlagen etc.

*Websites
CodeProject, planetsourcecode, myCSharp-FAQ, myCSharp-Artikel, myCSharp-Snippets, myCSharp-Suche

  • die 3 Bereiche: Forum, Artikel, Source-Downloads werden von verschiedenen Portalen jeweils mit sehr unterschiedlichen Gewichtungen abgedeckt.

Bilder-Galerie (MSDN + ObjectBrowser)

Ich mache hier nur Objectbrowser und MSDN.
Die MSDN bietet "mehr Information als erwartet". Sowohl zum angefragten Item, als auch an hervorragenden Artikeln zu Basis-Wissen. Allerdings, mit verengtem "Problem-Löse-Blick" läuft man schnell Gefahr, daran vorbei zu "brausen". Die Bilder sollen den Blick gerade auf dieses "mehr an Info" lenken.

Der Objectbrowser kann ebenfalls "mehr Information als erwartet" bieten - aber ganz anders: Hier hilft die strukturierte Übersicht stolpern, nämlich über Klassen oder Member, die evtl. elegantere Ansätze beinhalten, als was man grade selbst verfolgt. Die OB-Bilder zeigen auch ein paar Möglichkeiten, zu filtern oder zu gruppieren (um etwa speziell nach Ereignissen zu suchen).

Auf den Reflector gehe ich böserweise nicht ein. Er bearbeitet prinzipiell dasselbe Gebiet wie der OB, mit der weit über den OB hinausgehenden Möglichkeit der Disassemblierung. Aber es gibt ja eh schon diesen [Artikel] .NET Reflector

MSDN
Gegeben sei folgendes Code-Fragment:


System.IO.File.Copy(

... und hier wusste unser Autor nicht recht weiter. Also holt er sich die Kontext-Hilfe, indem er den Cursor auf Copy setzt und [F1] drückt.

Ergebnis:

Nichts, was man sich nicht auch hätte denken können.
Immerhin: es gibt 2 Überladungen, und eine davon ermöglicht, auch vorhandene Dateien ggfs. zu überschreiben.

Letztere gleich mal angucken:

Nanu? VisualBasic?

Nicht relevanten Sprachen kann man ausblenden

Inhaltlich sehen wir aber immer noch nichts wirklich neues - Scrollen wir mal weiter:

Hier beginnt, was ich meine mit_ "mehr Info als erwartet"_ - Nicht jeder denkt gleich, dass bei einem so einfachen Funktiönchen so viel schief gehen kann, odr?

Weiter gescrollt:

"Hinweise" sind häufig hochinteressant - _:::


File.Copy("Test.txt", @"..\Test.txt");

...und er kopiert mir die Datei ins drüber liegende Directory.
Das ist eben die besondere Stärke der MSDN, nämlich Zusatz-Informationen zu liefern, auch wenn sie in kein Schema passt (und daher anders kaum je auffindbar wäre).
Es ist also sehr geraten, die MSDN auch dann zu konsultieren, wenn man meint, genügend informiert zu sein.

Weiter gescrollt:

Ahh, Code-Sample! Immer sehr willkommen.

Weiter gescrollt:

Den "Siehe auch" - Abschnitt möchte ich dem geneigten Leser ebenfalls besonders ans Herz legen:
"Gewußt wie"-Artikel sind meist sehr praktische Anleitungen (naja relativ - aber immerhin lauffähig).
Die anderen im Bild unter "weitere Ressourcen" gelisteten Artikel (Datei und Stream-E/A, Grundlegende Datei-E/A) behandeln sehr wichtige, grundlegende Konzepte.

Hilfe-Index ist aber vorzuziehen (Toolbar oder Menu verwenden)
Dadurch erhält man links einen Navigations-Frame, voll mit für den Suchbegriff mehr oder weniger in Frage kommenden Artikel-Vorschlägen.
Ich gebe z.B. "file" ein, und wähle den Treffer "Informationen zur File-Klasse":

Der Navi-Frame ist auf Anhieb mit vorwiegend hochinteressanten Treffern gefüllt.
Besonders "Beispiele" und "Informationen zu ..." sind hervorzuheben: Beispiele sind praktisch, Treffer, die mit "Informationen zu..." beginnen, geben üblicherweise Einführungen in Thematiken, erläutern Konzepte etc. - Wissen, ohne das man wie der berühmte Ochs vorm Berg...

Und dann natürlich die lange Liste der File-Member - alles auf einen Blick!
Mit der Kontext-Hilfe hätte man dieses nie gefunden.

Das folgende Bild illustriert, dass MSDN natürlich auch eine Referenz der Sprache C# ist - imstande, Syntax-Fragen vollständig aufzuklären:

Such-Eingabe war hier einfach: "c"

Bevor ich die MSDN verlasse noch ein Tipp: Der Document-Explorer unterstützt leider nicht wirklich tabbed browsing.
Immerhin kann man per Kontextmenü das Fenster duplizieren, und dann im "Clon" zu weiteren Zielen aufbrechen, ohne das bisher gefundene zu verlieren.

Oder man tut ein Fundstück per Kontextmenü in die Hilfe-Favoriten (Die Abbildung zeigt ja auch diesen Kontext-Menü-Punkt).

Der ObjectBrowser

...beantwortet die Suche-Eingabe "file" mit geballter Information: 45 Member der Klasse File, incl. ihrer Parameter-Typen.

Schön übersichtlich auch, dass verschiedene Überladungen getrennt gelistet sind - bei MSDN müsste in verschiedene Verzweigungen gebrowst werden.
Kleiner Trick: Der linke Frame zeigt zunächst alle Treffer, die auf "file" matchen. Wir wählen den gewünschten Treffer an, navigieren einmal zurück, und dann wieder vor (entweder per Menü oder per Tasten [Alt<-], [Alt->]).
Jetzt zeigt der linke Frame die (Einordnung der Klasse in die Framework-Systematik:

Und das ist sehr nützlich, wenn man die Augen offen hält: Man bekommt zu sehen, was sonst noch im Namespace System.IO so herumfährt: Dinge wie DirectoryInfo, FileInfo, verschiedene Reader und Writer.
Und auch sehr übersichtlichen Einblick in die Vererbungshierarchie - ich habe mal für "FileStream" gezeigt, dass es IDisposable implementiert (der Grund, warum FileStreams in einen Using-Block gehören).
Unsere beiden Überladungen der Methode <span style="font-size: 12;">Copy</span> stehen an 4. und 5. Stelle - mal gucken, was der OB über sie weiß:

(ist bischen zusammen gedrückt, da ich mich auf Bildbreite 600Pix beschränke)
Jo, die "Essentials", kann man sagen - das ging jetzt aber ein ordentliches Stück flotter als mit der MSDN, zumal er auch wesentlich schneller lädt.
Dafür wird man Code-Beispiele, Programmier-Hinweise, Konzept-Erläuterungen etc. im OB vergeblich suchen.

Die hier angezeigte Dokumentation ist übrigens nichts anderes, als was der Programmierer der File.Copy()-Methode als "Dokumentations-Kommentar" vorangestellt hat.
Den geneigten Leser hindert nichts, seine Klassen und Klassen-Member ebenso ordentlich zu dokumentieren.😉

Ich mache mal einen kleinen Hüpfer zur Klasse Forms.Button, da kann man einige Features des OBs deutlicher zeigen:

Erstaunlich wenige Member der Klasse Button, nichtwahr? Weil nämlich die geerbten Member ausgeblendet sind. Zeigt man die mit an, sieht es so aus:

Da sind jetzt ca. 250 Member gelistet (Scrollbar beachten), etwas zu Lasten der Übersichtlichkeit.
Wir können z.B. jetzt auch gruppieren, und irrelevante Gruppen kollabieren:

...etwa, wenn nach Ereignissen gesucht wird.

Hinweisen möchte ich auch auf den "Durchsuchen"-Filter - "eigene Projektmappe" ist meist eine ganz sinnvolle Einstellung.

In dieser Einstellung werden die Projekte der aktuell in Bearbeitung stehenden Solution ebenso gelistet, wie alle anderen beteiligten Assemblies auch.

Nebenbei (im folgenden Bild): Meine Zusammenfassung der Klasse RichTextBoxUpdater (Doku-Tag: <Summary>...</Summary>).

Übrigens kann man auch im ObjectBrowser "Zu Definition gehen", sogar mit simplen Doppelklick (hier nicht gezeigt)!

Meine VB-ObjectBrowser -Schrulle
Tja, der VB-OB ist ein klein bischen besser als der von C#.
Vergleiche:

mit

VB hat weniger Treffer, nämlich die signifikanten. Das rührt daher, dass in C# jeder Konstruktor als Treffer gelistet wird, da namensgleich mit der gesuchten Klasse.
Dann unterscheidet VB zw. Funktionen und Methoden (C#: void methods), was eine nützliche Gruppierungs-Kategorie ist: Im Bild z.B. sind die Methoden "weg-kollabiert", sodass die Ansicht auf die sehr übersichtliche Auswahl von Funktionen mit Rückgabewert fokussiert.
Vor allem: VB zeigt schon in der Übersicht den Rückgabewert der Member an, und somit die vollständige Signatur.

Wenn man mag, kann man sich also eine VB-IDE öffnen, und den dortigen OB nutzen statt des C#-OBs.

Ja, zum Schluß bleibt noch eine _:::

Der frühe Apfel fängt den Wurm.