Добавление к коду комментариев

Чтобы приложения для расчета стоимости заработало должным образом, было добавлено совсем немного кода. Результаты проведенной работы отображаются на всех веб-страницах. Например, в моем варианте страницы tourprice_processor.asp содержимое XHTML-документа начинается только на строке 39, а остальное место занимают ASP-сценарии. При использовании ColdFusion XHTML-документ начинается в строке 18. По большей части в этом коде содержатся те же сценарии, выполняющие те же функции, – просто код ColdFusion занимает гораздо меньше места. PHP располагается где-то между ними, – контент XHTML-документа начинается со строки 28.

Если просмотреть код страниц tourprice.asp и tourprice_processor.asp до верхней строки, можно объяснить все сценарии, расположенные в нем (в случае с ASP и PHP существует одно исключение, о котором позже будет рассказано). Сценарии будут понятными не только потому, что вы приобрели опыт их написания, но и потому, что упражнения выполнялись недавно, и в голове остались свежие воспоминания о сценариях. Но если вернуться к ним хотя бы через несколько месяцев или показать кому-нибудь в первый раз, то понять, для чего нужен тот или иной участок кода, будет не очень просто.

Это довольно серьезная проблема, поскольку подобные документы нередко используются в течение нескольких лет, и разработчики успевают позабыть об их содержимом. Именно поэтому важно документировать код сценариев, чтобы он был понятен – как для вас, так и для тех, кто будет заниматься сайтом впоследствии.

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

1. Откройте документ tourprice.asp. Добавьте комментарий над кодом запроса.

   Для ASP следует добавить строку ниже открывающего тега <% в самом начале кода (до объявления переменной Dim rs_tourprices) и ввести в нее следующий комментарий, поясняющий, что создается набор записей на основе названий и идентификаторов туров из таблицы tbl_tours в базе данных. Кроме того, в этом комментарии объясняется, что данные используются в дальнейшем для заполнения раскрывающегося списка в форме:

   ' Creates a recordset of all the tour names and IDs from the tbl_tours table in the database/ the data is used later to populate the form drop-down menu.

   
   Для ColdFusion вверху документа следует ввести следующее:
   
   <!--- Creates a recordset of all the tour names and IDs from the tbl_tours table in the database/ the data is used later to populate the form drop-down menu. - -->
   
   Для PHP перед строкой, расположенной строке 3 и начинающейся с кода my_sql_select_db, следует ввести комментарий:
   
   // Creates a recordset of all the tour names and IDs from the tbl_tours table in the database/ the data is used later to populate the form drop-down menu.
   
   Во всех трех языках комментарии обозначаются особым образом. В языке VBScript (ASP) применяется одинарная кавычка (‘). Все, что расположено между этой кавычкой и концом строки, считается комментарием и игнорируется интерпретатором. В ColdFusion комментарий заключается в специальные теги. Они подобны тегам комментариев в HTML, за исключением того, что в HTML используются два дефиса, а в ColdFusion – три. Комментарий ColdFusion может включать несколько строк. В PHP однострочные комментарии могут обозначаться двумя косыми чертами (//) или знаком # в начале строки. Для создания многострочных комментариев в PHP применяется следующая синтаксическая конструкция: /* комментарий */.
   
   Поскольку комментарии пишутся с учетом синтаксиса языка, используемого на сервере (VBScript, ColdFusion Markup Language или PHP), а не по правилам синтаксиса HTML, они удаляются из документа перед отправкой страницы клиенту. Это означает, что документировать код можно произвольным образом и при этом не волноваться, что комментарии увидят посетители.
   
   
   
   
   увеличить изображение
   
   
2. Сохраните и закройте tourprice.asp, а потом откройте tourprice_ processor.asp.
   
   Большинство сценариев, используемых при работе приложения, содержатся в документе tourprice_processor.
   
   
3. Только пользователям ASP и PHP. К первому участку кода после объявления <%LANGUAGE (только ASP) и к участкам <!—include (ASP) или require_once (PHP) добавьте приведенный ниже комментарий, не упуская одиночной кавычки ' (ASP) или двойного слэша // (PHP) в начале строки. В этом комментарии указывается, что созданный небольшой сценарий, сгенерированный Dreamweaver, предназначен для облегчения работы с динамическим запросом:
   
   
   
   A small script generated by Dreamweaver to help with the dynamic query
   
   Комментарии ASP и PHP всегда должны находиться, соответственно внутри тегов <% %> и <?php ?>.
   
   Этот сценарий не упоминался в упражнениях, поскольку Dream-weaver автоматически добавил его при создании динамического запроса (а точнее, в момент создания критерия для фильтрации данных: tourID = form variable tourName). Этот комментарий поясняет, для чего предназначен участок кода и каким образом он попал на страницу.
   
   В ColdFusion этот сценарий отсутствует, поскольку он реализован несколько иным (и более простым) способом.
   
   
   
   
   
   
4. Отыщите сценарий, создающий набор записей, и добавьте к нему следующий комментарий "Queries the database for the tour name, adult price, and child price; data is filtered so that the only record retrieved corresponds to what the user entered the form". (В этом комментарии поясняется, что в базу данных направлен запрос на поиск названия тура, а также его стоимости для взрослых и для детей. Данные фильтруются таким образом, чтобы только одна извлеченная запись соответствовала значению, указанному пользователем в форме.)
   
   В ASP сценарий запроса начинается с объявления используемых в нем переменных: Dim rs_tourprices_filtered.
   
   В ColdFusion сценарий запроса найти довольно легко, поскольку он размещен внутри тегов <cfquery>.
   
   В PHP сценарий начинается со строки mysql_select_db.
   
   Следует помнить о применении правильного синтаксиса при вставке комментариев.
   
   
   
   
   увеличить изображение
   
   
5. Найдите сценарий для проверки правильности заполнения формы и добавьте следующий комментарий "Form validation script; redirects user back to tourprice.asp if form fields do not have numeric values". (В комментарии поясняется, что данный участок кода является сценарием, проверяющим правильность заполнения формы. Помимо этого указывается, что после выполнения сценария посетитель вернется обратно на страницу tourprice.asp, если поля формы не будут содержать числовых значений)
   
   
   
   
   
   
   В ASP этот сценарий начинается с кода If Not IsNumeric. В ColdFusion – с кода <cfif Not IsNumeric. В PHP – с кода if (is_numeric.
   
   
   
   
   увеличить изображение
   
   
6. Найдите сценарий для расчета стоимости путешествий и добавьте следующий комментарий "Collects data for number of adults and children, and the prices for both adults and children; multiplies data to calculate total". (В комментарии указывается, что после выполнения сценария будут получены данные о количестве взрослых и детей, а также стоимость выбранного тура для взрослых и детей. Помимо этого, уточняется, что для получения итоговой стоимости будут проведены соответствующие расчеты.)
   
   

После такой интенсивной работы над этим сценарием в предыдущих упражнениях найти его самостоятельно не составит особого труда.

Теперь, после завершения полного цикла по созданию указанного сценария, следует лишь сохранить файлы и загрузить их на сервер.


увеличить изображение


Содержание  Назад  Вперед

---