Использование “$”для переменной цикла в подобной среде плохая идея, впрочем, ничем не лучше

Использование “$”для переменной цикла в подобной среде плохая идея, впрочем, ничем не лучшеНе следует втолковывать очевидное посредством многословных имен переменных.

С теми же проблемами мы сталкиваемся и в комментариях, сообщающих очевидную информацию, например // Constructor next to a class constructor (Конструктор, следующий за конструктором класса). К сожалению, комментарии такого сорта весьма распространены: обычно они вставляются в код чересчур заботливой средой разработки (IDE). В лучшем случае, они добавляют шуму в исходный текст кода. В худшем со временем они становятся просто неверными.

Многие комментарии просто не сообщают никакой полезной информации. Например, какая польза вам от комментария:

method allows you to passthrough”(Данный метод позволяет вам пересылать данные) к методу под названием passth rough()? Комментарии такого рода лишь отвлекают внимание и со временем могут стать неуместными (если вы мотом измените название метода на sendToHost()).

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

Назначение (Purpose): Зачем существует этот метод?

Требования (Preconditions, предпосылки или предварительные условия): Какие входные данные требуются, и в каком состоянии должен находиться объект, чтобы данный метод работал?

Обещания (Post - conditions, результаты или окончательные условия): В каком состоянии находится объект, и какие значения возвращаются после успешного выполнения данного метода?

Исключения (Exceptions): Что может произойти не так, как надо, и какие исключения могут быть обработаны?

Благодаря таким инструментам, как RDoc, javadoc, и ndoc, у вас есть возможность легко создавать полезную, хорошо отформатированную документацию непосредственно из комментариев, встроенных в ваш код.

Эти средства берут ваши комментарии и создают на их базе симпатичный HTML - файл, снабженный гиперссылками.

Ниже представлены некоторые выдержки из документированного кода на С. Обычная строка комментариев начинается с а комментарии, которые предназначены для документации, начинаются с “///”(разумеется, они работают и как обычные комментарии).

Using System;
namespace Bank
(
/// <summary>
/// A BankAccount represents a customers non - secured deposit /// account in the domain (see Reg 47.5, section 3).
/// </surnmary> public class BankAccount
(
/// <summary>
/// Increases balance by the given amount.
/// Requirements: can only deposit p positive amount.
/// </summary>
III
/// <param name = "depositAmount">The amount to deposit, already /// validated and converted to a Money object /// </param>
///
/// <param name = depositSource">Origination of the monies /// (see FundSource for details)
/// </param>
III <returns>Resulting balance as a convenience /// </returns>
III
III Exception cref = MlnvalidTransactionException”>
/// If depositAmount is less than or equal to zero, or FundSource /// is invalid (see Reg 47.5 section 7)
Ш or does not have a sufficient balance.
Ill </exception> public Money Deposit(Money depositAmount, FundSource depositSource)
(
)
)
)

Фрагмент документации, созданный с помощью ndoc на базе комментариев в приведенном примере С - кода. Javadoc для Java, RDoc для Ruby и другие подобные средства работают аналогичным образом.

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

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

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

На что это похоже

Комментарии должны стать для вас хорошими друзьями; вы можете только взглянуть на них и уже будете точно знать, что и как делает код и зачем.

Сохраняйте равновесие

Паскаль однажды сказал, что у него нет времени писать короткое письмо и потому ему придется писать длинное. Потратьте время на написание коротких комментариев.

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

Писать в комментариях, что именно делает код, приносит мало пользы; лучше объясните, почему он это делает.

Когда вы переопределяете метод, сохраняйте назначение базового метода и оставляйте комментарии, в которых описывается цель и ограничения для исходного (переопределяемого) метода.

Иногда просто охото отдохнуть и почитать стихи о любви, ведь любовь это прекоасно!

tel-icq