О комментариях. Часть 2

В прошлый раз мы рассмотрели основные подходы к комментированию кода, а в этот раз я хочу рассмотреть эти советы на простых практических примерах.

1. Комментарии из серии «ни о чем». Или зачем дублировать код?

Основные претензии к комментариям заключаются в том, что они устаревают или просто дублируют код, описывая его на том же уровне абстракции, что и сам код. Ниже представлен утрированный антипаттерн:

public void ProcessEmployee(int id)
{
    // Получаем всех сотрдуников
    IEnumerable<Employee> employees = GetEmployees();
 
    Employee employee = null;
    // Перебираем коллекцию всех сотрудников
    foreach (var e in employees)
    {
        // Если Id текущего сотрудника совпадает с заданным
        if (e.Id == id)
        {
            // Нашли требуемого сотрудника
            employee = e;
            // Прерываем цикл
            break;
        }
    }
 
    // Генерируем исключение, если сотрудник не найден
    if (employee == null)
    {
        throw new InvalidOperationException("Employee with specified Id was not found");
    }
 
    // Работаем с найденным сотрудником
}

Такие комментарии не просто бесполезны, но и вредны, поскольку не добавляют ничего нового. В этом случае, они просто дублируют каждую императивную конструкцию, описывая, как мы решаем задачу.

2. Комментарий блока кода

Вместо повторения каждого шага, мы можем добавить комментарий, который скажет, что же мы делаем в нижележащем блоке кода.

public void ProcessEmployee(int id)
{
    // Находим сотрудника с заданным идентификатором, бросаем исключение,
    // если такого сотрудника нет
    IEnumerable<Employee> employees = GetEmployees();
 
    Employee employee = null;
    foreach (var e in employees)
    {
        if (e.Id == id)
        {
            employee = e;
            break;
        }
    }
 
    if (employee == null)
    {
        throw new InvalidOperationException("Employee with specified Id was not found");
    }
 
    // Работаем с найденным сотрудником
}

3. Заменяем комментарий высокоуровневым кодом

Но вместо того, чтобы описывать императивный код, мы можем переписать его в более декларативной форме. В этом случае сам код будет говорить, что он делает, а в комментарие мы можем дать пояснение текущему поведению:

public void ProcessEmployee(int id)
{
    IEnumerable<Employee> employees = GetEmployees();
    
    // Отсутствие сотрудника с заданным Id означает рассогласованное состояние системы;
    var employee = employees.Single(e => e.Id == id);
 
    // Работаем с найденным сотрудником
}

4. Используем контракты вместо комментариев

С самого начала, логика поиска сотрудника требовала отдельного метода. Но помимо простого выделения метода GetEmployeeById мы можем перенести наш комментарий в виде постусловия метода и в качестве упражнения добавить еще и предусловие: 

private Employee GetEmployeeById(int id)
{
    Contract.Requires(id > 100, 
        "Идентификаторы меньшие 100 зарезервированы и использоваться не могут.");
 
    Contract.Ensures(Contract.Result<Employee>() != null,
     "Отсутствие сотрудника с заданным Id означает рассогласованное состояние системы.");
            
    IEnumerable<Employee> employees = GetEmployees();
    var employee = employees.SingleOrDefault(e => e.Id == id);
 
    if (employee == null)
        throw new InvalidOperationException(
            string.Format("Employee with Id = '{0}' was not found.", id));
 
    return employee;
}
 
public void ProcessEmployee(int id)
{
    var employee = GetEmployeeById(id);
 
    // Работаем с найденным сотрудником
}

ПРИМЕЧАНИЕ
В случае использования LINQ можно использовать SingleOrDefault с последующей проверкой результата или использовать метод Single. Разница заключается в том, насколько информативным будет сообщение в генерируемом исключение; в случае SingleOrDefault мы генерируем исключение с более информативным сообщением об ошибке, а в случае использования метода Single, сообщение об ошибке будет более туманным: “Sequence contains no matching elements”. Так что, какой вариант вы будете использовать – решать вам.

Очень часто мы используем комментарии для неформального описания системы; фактически, мы таким образом переносим часть спецификации прямо в код. Зачастую мы можем выразить подобные аспекты более строго в форме предусловий, постусловий и инвариантов. Однако контракты, в отличие от комментариев, связаны с кодом значительно сильнее и не страдают проблемой старения.

При этом контракты продолжают играть роль комментариев, поскольку предусловия и постусловия «интегрируются» в сгенерированную xml-документацию в виде отдельных секций <pre> и <post>, что делает их легко доступными из среды разработки.

Какой вариант выбрать: последний или предпоследний? Не зная решаемой задачи, сделать этого практически невозможно. Контракты и более информативные сообщения в исключениях приводят к более объемному коду, поэтому прибегать к ним стоит тогда, когда это действительно того стоит.