Commenter essayer des déclarations de capture

Question

Quel est le lieu approprié pour expliquer le traitement des erreurs dans une instruction try-catch? Il semble que vous puissiez mettre des commentaires explicatifs au début du bloc try ou du bloc catch.

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

    // Error handling code

}

Answer 1

Je fais habituellement ce qui suit. Si une seule exception est gérée, cela ne me dérange généralement pas, car cela devrait être auto-documenté.

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

"Un commentaire est un mensonge" . Travaillez sur les noms de variables et la logique générale afin de l'éviter. Et si vous avez vraiment besoin de mentir, faites-le à l'intérieur du bloc d'arrêt.

Answer 3

Je ne pense pas que ça compte, du tout.

Je pense que l'importateur à retenir avec les commentaires consiste à expliquer pourquoi le code est tel qu'il est et non ce que le code fait, en tout premier lieu. Cela ne veut pas dire que vous ne devriez pas expliquer la logique complexe dans un commentaire concis, mais que le pourquoi est tellement plus important.

Answer 4

Qu'en est-il de la configuration du code pour qu'il n'ait pas besoin de commentaires supplémentaires?

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

Inutile de documenter si vous pouvez utiliser le nom de votre variable et de votre méthode pour montrer ce qui se passe. Pas besoin de documenter si vous devez vous connecter ou lever les exceptions - le message de journalisation dans le code source devrait de toute façon être explicite. La seule fois où vous devriez avoir besoin de documentation supplémentaire dans votre code, c’est quand il est totalement non-évident que le code le fait. code à l'avenir.

Modifier: pour clarifier un peu, voici un peu plus sur la manière dont je pourrais utiliser ces "captures". instructions destinées à fournir des informations utiles à la fois au programmeur de maintenance et aux utilisateurs / support / assurance qualité / toute autre personne utilisant le logiciel. Également une illustration du genre de situation où je voudrais absolument ajouter des commentaires supplémentaires dans le code:

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

Ne commentez certainement pas le haut de la page, car que pouvez-vous utilement dire si vous ne démarrez pas "commencer un bloc de gestion des exceptions ici"? Les commentaires sur les déclarations de capture sont meilleurs, mais en général, encore une fois, qu'allez-vous dire? "Gérer une exception NullPointerException"?

Je voudrais un commentaire si vous devez faire quelque chose d'intéressant, comme chaîner une exception de domaine d'application.

Answer 6

Je pense qu'un essai / capture bien écrit devrait être concis et spécifique. Je suis d'accord avec @Jason sur le fait que le pourquoi est plus important mais qu'il est également important de garder le code aussi clair que possible.

Cela vous aiderait également si vous utilisiez des exceptions spécifiques. Si vous utilisez Java par exemple, essayez d'attraper une exception NullPointerException plutôt qu'une exception générique. Cela devrait expliquer pourquoi la capture d’essai existe et ce que vous faites pour la résoudre.

Answer 7

L'emplacement n'a pas d'importance tant que vous êtes cohérent. Ma préférence personnelle est la suivante:

//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

Je sais que ce n'est pas la réponse que vous cherchez, mais ne commentez pas du tout. Si votre code n'est pas assez clair pour être autonome sans commentaire, vous devez le refactoriser jusqu'à ce qu'il le soit. Jeffrey Palerm o vient d'écrire un article de blog qui le dit le mieux.

Généralement, les commentaires ont tendance à documenter:

• Code trop compact. Ce qui ressemble à ceci: ++ i? - g: h-i;
• Longs blocs de code à récapituler
• Code disponible ou dont la raison d'être n'existe pas clairement

Voir ci-dessous un exemple simplifié de commentaires simples sur votre bloc d'exception, ainsi qu'une version qui élimine le besoin de commentaires.

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;
    }
}

Bien que les commentaires ci-dessus favorisent la possibilité de réutilisation, vous devez essentiellement gérer le code et les commentaires. Il est possible (et préférable) de reformuler ceci afin qu'il soit plus clair sans commentaires.

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;
}

Ce dernier exemple peut sembler être plus de code pour un avantage très subtil, mais les gains ne peuvent pas être surestimés. Le code est tout aussi compréhensible, mais vous avez l’avantage de ne pas avoir besoin de disposer d’un ensemble séparé de métadonnées (commentaires) pour expliquer le code. Le code s’explique. Si votre bloc de code de capture est trop long et a besoin d'un commentaire, pensez à le transformer en une méthode distincte afin d'améliorer la lisibilité.