Wie kommentiere ich Subs und Funktionen?

    • VB.NET

    Es gibt 3 Antworten in diesem Thema. Der letzte Beitrag () ist von ErfinderDesRades.

      Wie kommentiere ich Subs und Funktionen?

      Hey und und Herzlich Willkommen.

      Ich möchte dir mal zeigen, wie Subs und Funktionen sauber und VisualStudio-Konform kommentiert werden können, da mir im Showroom immer wieder Libs auffallen, die durch saubere Kommentare erheblich an Übersicht gewinnen könnten.

      VisualStudio hilft dir sogar dabei. Also lass uns loslegen.

      Bewege dich zu der Funktion, die du Kommentieren möchtest. Ich nehme diese hier:

      VB.NET-Quellcode

      1. Private Function tutNix(ByVal a As Integer, ByVal b As String) As Integer
      2. Return a
      3. End Function


      Dann positioniere den Cursor über dieser Funktion und gebe folgendes ein (Auchtung: Du musst es von Hand eingeben, sonst funktionierts nicht.)

      Quellcode

      1. '''


      VisualStudio erstellt dann folgendes Gebilde:

      VB.NET-Quellcode

      1. ''' <summary>
      2. '''
      3. ''' </summary>
      4. ''' <param name="a"></param>
      5. ''' <param name="b"></param>
      6. ''' <returns></returns>
      7. ''' <remarks></remarks>


      Die einzelnen Parameter unterscheiden sich natürlich von Funktion zu Funktion, aber so siehts aus falls du die oben angeführte Funktion benutzt hast.

      Trage dann die Informationen zu deiner Funktion ein:
      summary - Eine zusammenfassende Beschreibung deiner Funktion
      param - Beschreibt die zu übergebenden Parameter
      returns - Beschreibt den Wert, der zurückgegeben wird.
      remarks - Sonstige Informationen (Copyright, Besonderheiten usw.)

      Ich habe das Kommentar wie folgt ausgefüllt:

      VB.NET-Quellcode

      1. ''' <summary>
      2. ''' Diese Funktion tut nix.
      3. ''' </summary>
      4. ''' <param name="a">Wird für absolut nichts benötigt.</param>
      5. ''' <param name="b">Der auch nicht.</param>
      6. ''' <returns>Nichts relevantes.</returns>
      7. ''' <remarks>SolaSoft</remarks>


      Wenn du die Funktion dann aufrufst, werden die oben eingegebenen Informationen im ToolTip angezeigt:



      Übrigens kann diese Methode auch auf Subs, Klassen, Interfaces, Events, Module usw angewendet werden. Je nach Typ kommen dann unterschiedliche Parameter hinzu.

      So, gestalte deine Librarys ein wenig übersichtlicher :)

      MFG Solaris

      Dieser Beitrag wurde bereits 2 mal editiert, zuletzt von „Solaris“ ()

      Solaris schrieb:

      remarks - Informationen über den Autor.

      Remarks steht nicht für die Infos über den Autor, sondern für "sonstige Bemerkungen" vom Autor über diese Methode.

      Außerdem lassen sich nicht nur Subs und Funktionen so kommentieren, sondern auch Klassen, Interfaces, Events, veraltete Module und so weiter. Eigentlich kann man alles damit dokumentieren.

      Außerdem muss hinzugefügt werden, dass diese Dokumentation in einer externen XML-Datei bereitgestellt wird; also nicht in der Assembly selbst. Z.B. in der Datei "DeinAssemblyname.xml". Man kann so viel dokumentieren wie man will; wenn diese XML-Datei nicht mitgeliefert wird, bringt das nichts. ;)

      Hier gibt es das Ganze noch mal auf MSDN:
      msdn.microsoft.com/de-de/library/z04awywx%28v=vs.90%29.aspx

      Hier noch eine Liste mit weiteren Tags, die nicht automatisch generiert werden:

      Quellcode

      1. Tag Verwendung Attribute
      2. example Anwendungsbeispiel für das jeweilige API-element.
      3. Verwendet meist das <code> tag. keine
      4. exception Beschreibt eine Exception die auftreten kann. cref *
      5. include Bindet eine externe XML-Datei ein. file, path *
      6. param Beschreibt einen Parameter einer Methode oder Eigenschaft name *
      7. permission Gibt die Zugangsberechtigungen bzw. die Gültigkeit (Scope) eines Typmitglieds wieder cref *
      8. remarks Beschreibt einen Typ oder eine Klasse keine
      9. returns Gibt den Rückgabewert einer Methode wieder keine
      10. seealso Gibt einen Verweis auf verwandte Themen cref *
      11. summary Beschreibt Typmitglieder wie Methoden, Eigenschaften, Felder keine
      (Quelle: aspheute.com/artikel/20020730.htm)
      Von meinem iPhone gesendet

      Leuts, auch wenn Microsoft da unsinnige Richtlinien herausgibt: Stand der Technik ist, dass man Kommentare allgemein überflüssig machen sollte durch intelligentes CodeDesign.
      Und Dokumentations-Kommentare sind auch nur Kommentare.

      Wer also eine Methode "tutNix()" kommentiert mit

      VB.NET-Quellcode

      1. ''' <summary>
      2. ''' Diese Funktion tut nix.
      3. ''' </summary>
      zeigt vor allem, dasser nicht nachdenkt, bei dem, wasser tut.

      Denn die Methode ist perfekt selbsterklärend, und Kommentation oder gar Dokumentation erübrigt sich vollständig.

      Überflüssige Kommentare blähen die Code-Dateien auf und lenken den Entwickler auch selbst davon ab, die Kommentare zu schreiben, die wirklich notwendig sind.
      Und für den Leser gehen die notwendigen Kommentare denn auch unter im "Dokumentations-Gelaber".

      Beispiel eines notwendigen Komments:

      VB.NET-Quellcode

      1. ''' <summary>
      2. ''' returnt die typisierte Datarow am index. Bei ungültigem index Nothing (keine OutOfRange-Exception!)
      3. ''' </summary>
      4. <Extension()> _
      5. Public Function At(Of T As DataRow)(ByVal subj As BindingSource, ByVal index As Integer) As T
      6. Return DirectCast(DirectCast(subj(index),DataRowView).Row, T)
      7. End Function

      Die Kommentierung dieser Extension-Methode
      BindingSource.At(Of T As DataRow)(index As Integer) As T
      ist auch fast(!) überflüssig. Nur dasses bei ungültigem Index keine Exception gibt, ist ein kommentar-erforderndes Detail - der Rest ist selbsterklärend, die Extension-Technologie mal als bekannt vorrausgesetzt.

    Facebook
    Telefonspende