Kommentieren try-catch-Anweisungen

Question

Was ist der richtige Ort, um zu erklären, die Fehlerbehandlung in einem try-catch-Anweisung?Wie es scheint, könnten Sie die Erläuterungen am Anfang der try-block oder im catch-block.

// Possible comment location 1
try
{   
    // real code
}
// Possible comment location 2
catch
{
    // Possible comment location 3

    // Error handling code

}

Answer 1

Normalerweise mache ich die folgenden. Wenn es nur eine Ausnahme behandelt wird, ich in der Regel nicht die Mühe machen, da es sollte selbsterklärend sein.

try
{   
    real code // throws SomeException
    real code // throws SomeOtherException
}
catch(SomeException se)
{
    // explain your error handling choice if it's not obvious
}
catch(SomeOtherException soe)
{
    // explain your error handling choice if it's not obvious
}

Answer 2

"Ein Kommentar ist eine Lüge" . Die Arbeiten an diesen Variablennamen und die allgemeine Logik, so dass Sie es vermeiden können. Und wenn Sie wirklich liegen müssen, tun Sie es in dem catch-Block.

Answer 3

Ich glaube nicht, es darauf ankommt, überhaupt nicht.

Ich denke, der Import Sache zu erinnern, mit Kommentierung zu adressieren ist, warum der Code ist so wie es ist und nicht was der Code tut, in erster Linie. Dies ist nicht zu sagen, dass Sie nicht komplexe Logik in einem kurzen Kommentar erklären sollten, aber das Warum ist so viel wichtiger.

Answer 4

Was ist nur den Code einrichten, so dass es keine zusätzlichen Kommentare braucht?

try
{ 
   performDifficultAct( parameter );
}
catch (ArgumentOutOfRangeException couldNotFindArgument)
{
   // handle exception
}
catch (Exception otherUnknownException )
{
   // handle exception
}

Keine Notwendigkeit zu dokumentieren, wenn Sie Ihre Variable und Methode Namensgebung verwenden, um zu zeigen, was los ist. Keine Notwendigkeit zu dokumentieren, wenn Sie die Ausnahmen zu protokollieren oder zu erhöhen, haben - die Logging-Nachricht im Quellcode sollte ohnehin selbsterklärend sein. Das einzige Mal, wenn Sie zusätzliche Dokumentation in Ihrem Code benötigen sollten, wenn es völlig nicht offensichtlich ist, was der Code tut oder ther ist ein einfach zu verpassen Gotcha oder mehrdeutig Schritt, den Sie hinzufügen, dass müssen wird eine Erklärung brauchen für jedermann auf der Suche Code in der Zukunft.

Edit: ein wenig zu verdeutlichen, hier ein bisschen mehr, wie ich diese „fangen“ Anweisungen verwenden könnten nützliche Informationen sowohl zu einem Wartungs Programmierer und Anwender / support / QA / alle anderen zur Verfügung zu stellen, die die Software. Auch eine Darstellung der Art von Situation, wo ich unbedingt möchte zusätzliche Kommentare im Code hinzuzufügen:

public void PerformSomeActionOrOther(string parameter)
{
  try
  { 
     // For some reason an eleven character string causes a bluescreen from Kernel32
     if (parameter.Length==11) parameter+=" ";

     performDifficultAct( parameter );
  }
  catch (ArgumentOutOfRangeException couldNotFindArgument)
  {
     this.Log.WriteLn("Argument out of range exception in ArbitraryClass.PerformSomeActionOrOther");
     this.Log.WriteLn(String.Format("Probable cause is that {0} is not in the array", parameter));
     this.Log.WriteLn(String.Format("Exception: {0}", couldNotFindArgument.Message));
  }
  catch (Exception otherUnknownException )
  {
     this.Log.WriteLn("Unexpected exception in ArbitraryClass.PerformSomeActionOrOther");
     this.Log.WriteLn(String.Format("Exception: {0}", otherUnknownException.Message));
     throw( otherUnknownException );
  }
}

Answer 5

Definitiv nicht Kommentar die Spitze, denn was kann man sinnvoll sagen, außer "starten einer exception handling block hier"?Kommentare, die auf die catch-Anweisungen besser sind, aber im Allgemeinen wieder, was Sie gonna sagen?"Griff eine NullPointerException"?

Ich würde mich für ein Kommentar IFF, die Sie brauchen, um zu sagen, dass du etwas tust spannend, wie die Verkettung mit einer Anwendung-domain Ausnahme.

Answer 6

Ich denke, ein gut geschriebenes try / catch prägnant und spezifisch sein sollte. Ich stimme mit @ Jason, dass die Warum ist wichtiger, aber ebenso ist es wichtig, den Code innerhalb Fang so kurz wie möglich zu halten.

Es würde auch helfen, wenn Sie bestimmte Ausnahmen verwendet gefangen werden. Wenn Sie Java zum Beispiel verwenden, versuchen, eine Nullpointer eher als eine allgemeine Ausnahme zu fangen. Dies sollte erklären, warum die Try-Catch vorhanden ist und was Sie tun, um es zu lösen.

Answer 7

Die Lage spielt keine Rolle, solange Sie konsistent sind. Meine persönliche Präferenz ist wie folgt:

//comment 1: code does XYZ, can cause exceptions A, B, C
try {
    //do something
}
//comment 2: exception A occurs when foo != bar
catch (ExceptionA a) {
    //do something
}
//comment 3: exception B occurs when bar is null
catch (ExceptionB b) {
    //do something
}
//comment 4: exception B occurs when foo is null
catch (ExceptionC c) {
    //do something
}

Answer 8

Ich weiß, das ist nicht die Antwort, die Sie suchen, aber überhaupt nicht äußern. Wenn Ihr Code nicht klar genug, um auf eigenen Beinen stehen, ohne zu kommentieren, dann sollten Sie es Refactoring, bis es ist. Jeffrey Palerm o nur schrieb ein Blog-Post , die es am besten, heißt es.

Normalerweise Kommentare sind in der Regel entweder zu dokumentieren:

• Code, zu kompakt ist. Dinge, die wie folgt aussehen: ++i?--g:h-i;
• Long Codeblöcke, die zusammengefasst werden müssen
• Code, der entweder Einweg oder hat er keinen klaren Grund für bestehende

Siehe unten für ein vereinfachtes Beispiel für einige einfache auf Ihrem Ausnahmeblock zu kommentieren, und eine Version, die die Notwendigkeit für Kommentare beseitigt.

bool retries = 0;
while (retries < MAX_RETRIES)
{
    try
    {
        ... database access code
        break;
    }
    // If under max retries, log and increment, otherwise rethrow
    catch (SqlException e)
    {
        logger.LogWarning(e);
        if (++retries >= MAX_RETRIES)
        {
            throw new MaxRetriesException(MAX_RETRIES, e);
        }
    }
    // Can't retry.  Log error and rethrow.
    catch (ApplicationException e)
    {
        logger.LogError(e);
        throw;
    }
}

Während die obigen Ausführungen Wiederverwertbarkeit fördern, haben Sie im Wesentlichen sowohl den Code und die Kommentare zu halten. Es ist möglich (und bevorzugt) das Refactoring, so dass es klarer unkommentiert ist.

bool retries = 0;
while (canRetry(retries))
{
    try
    {
        ... database access code
        break;
    }
    catch (SqlException e)
    {
        logger.LogWarning(e);
        retries = incrementRetriesOrThrowIfMaxReached(retries, e);
    }
    catch (ApplicationException e)
    {
        logger.LogError(e);
        throw;
    }
}

...

private void incrementRetriesOrThrowIfMaxReached(int retries, Exception e)
{
    if (++retries >= MAX_RETRIES)
        throw new MaxRetriesException(MAX_RETRIES, e);

    return retries;
}

private bool canRetry(int retries)
{
    return retries < MAX_RETRIES;
}

Das letzte Beispiel kann für einen sehr subtilen Nutzen wie mehr Code erscheinen, aber die Gewinne können nicht hoch genug eingeschätzt werden. Der Code ist ebenso verständlich, aber Sie haben den Vorteil, dass Sie nicht brauchen einen separaten Satz von Metadaten (Kommentare), um den Code zu erklären zu haben. Der Code erklärt sich. Wenn Ihr Block catch Code zu lang und muss Kommentar zu fassen, darüber nachzudenken, es zu einem separaten Verfahren, um die Lesbarkeit zu verbessern Refactoring.