Если код труден для чтения, ему требуются комментарии, Подробно объясняй, строчка за строчкой, что ты делаешь.

Если код труден для чтения, ему требуются комментарии, Подробно объясняй, строчка за строчкой, что ты делаешь.Обычно программисты ненавидят писать документацию. Это потому, что документация, как правило, хранится отдельно от кода, и постоянно обновлять ее параллельно с кодом довольно трудно. Как результат, нарушается принцип DRY (Donl Repeat Yourself He повторяйтесь) [HTOO]), а сама документация может лишь вводить пользователей в заблуждение, а этот обычно хуже, чем полное отсутствие документации.

Более эффективное описание кода достигается комбинированием следующих двух приемов: говорить языком самого кода и использовать комментарии для сообщения не кодовой информации.

Если вы читаете метод, желая понять, что он делает, у вас может уйти на это уйма времени и сил, прежде чем вы сможете использовать этот метод в своем коде. С другой стороны, всего несколько строчек комментария с объяснением поведения метода могут заметно облегчить вашу жизнь. Вы быстро можете понять, для чего он нужен, каковы ожидаемые результаты и за чем необходимо следить т.е. в этом случае вы тратите намного меньше усилий.

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

Имена могут играть важнейшую роль. Зачастую тот, кто читает код, ограничивается чтением имен программных элементов. Хорошо подобранные имена могут точно передать ваши намерения и сообщить любую информацию читателю вашего кода. С другой стороны, применение искусственных схем именования (например, в венгерской нотации, теперь уже непопулярной) может серьезно затруднить чтение кода и его понимание. Эти схемы обрушивают па пас поток низкоуровневой информации о типах данных, жестко закодированной в именах переменных и методов, что делает код хрупким, негибким.

При хорошо подобранных именах и четко обозначенных ветвях выполнения код почти не нуждается в комментариях. На самом деле, когда Энди и его соавтор Дэйв Томас написали первую книгу о языке программирования Ruby, они фактически могли описать (документировать) весь язык с помощью интерпретатора Ruby, который читает код. И это здорово, когда код говорит сам за себя, вместо того чтобы полагаться на комментарии: создатель Ruby, Юкихиро Мацумого (Yukihiri Matsumoto) японец, а Энди и Дейв в японском языке дальше “сукияки”и “сакэ" не продвинулись.

Что значит хорошо подобранное имя? Это имя, которое несет максимум верной информации дня читателя кода. Плохое имя не передает никакой информации, а ужасное имя сообщает неверную информацию.

Например, название readAccount() для метода, который на самом деле записывает адресные данные на диск, можно считать ужасным.

foo великолепное, исторически сложившееся имя доя временной переменной, но оно ничего не сообщает о намерениях автора кода. Старайтесь избегать непонятных имен переменных. Короткое имя не обязательно будет непонятным: " традиционно используется как переменная цикла во многих языках, a ”обычно обозначает переменную типа String (строка). Это естественные обозначения, принятые во многих языках, и, хотя они короткие, их нельзя отнести к непонятным именам.

tel-icq