Соглашения в коде JavaServer Pages
Соглашения в коде JavaServer Pages
Поскольку JSP (JavaServer Pages) очень широко применяется во всем мире для написания web-приложений, многие JSP-программисты и web-разработчики, которые начинают разрабатывать и поддерживать подобные приложения, сталкиваются с той же проблемой, что и многие Java-разработчики: "Как нам структурировать JSP-код таким образом, чтобы его было легко читать, писать, а также обеспечить дальнейшую поддержку реализованного приложения?" В этой статье мы рассмотрим набор стандартных соглашений для написания JSP-страниц и приложений (версии JSP 1.1 и 1.2), которых было бы полезно придерживаться и при разработке типичных программных проектов, использующих web-компоненты.
Существующая на данный момент версия JSP 2.0 ( http://jcp.org/en/jsr/detail?id=152 ), практически полностью совместимая с 1.2, предоставляет разработчикам совершенно новый стиль в программировании web-приложений (без определений, скриптлетов и выражений) и имеет ряд новых особенностей, к которым также отчасти могут быть применены рассмотренные здесь соглашения.
Предполагается, что вы знакомы с JSP и Java.
Зачем вообще нужны соглашения в коде?
Кодовые соглашения важны и должны применяться программистами и web-разработчиками по ряду причин:
1. Они улучшают читабельность программных артефактов (под артефактами понимаются программные элементы разрабатываемого приложения).
2. Они позволяют уменьшить затраты усилий на управление проектом.
3. Они выводят ваш код на новый уровень, и он подпадает под общепринятые стандарты.
Имена файлов и их расположение
Именование файлов позволяет инструментами и web-контейнерами различных производителей определять типы файлов и интерпретировать их надлежащим образом. Следующая таблица представляет список рекомендаций по именованию и расположению разного рода файлов, используемых при написании web-приложений:
Теперь сделаем некоторые замечания и пояснения относительно приведенной выше таблицы.
Первое: <context root> — это корневой путь к директории, в которой располагается разрабатываемое вами web-приложение (корневая директория внутри .war-файла).
Второе: <subsystem path> — используется для логического разделения и группировки динамических и статических web-страниц. Для небольших web-приложений этот параметр может быть пустой строкой.
Третье: под JSP-фрагментом понимается какой-то JSP-код, который впоследствии может быть включен в другую JSP-страницу. JSP-фрагменты могут именоваться, как это видно из таблицы, как с суффиксом .jsp, так и с суффиксом .jspf и должны быть расположены либо в директории /WEB-INF/jspf, либо в одной директории со статическим содержимым соответственно. Те JSP-фрагменты, которые не представляют собой полноценной web-страницы, всегда должны именоваться с суффиксом .jspf и размещаться в /WEB-INF/jspf.
Наконец, всегда желательно располагать файлы — описатели библиотеки тэгов (tag library descriptor) и прочие не предназначенные для пользователей файлы в директории WEB-INF/ или в какой-нибудь из ее поддиректорий, поскольку в таком случае содержимое этих файлов будет недоступно для клиентов-пользователей, т.к. никакой из web-контейнеров не будет выдавать по запросу никаких файлов из WEB-INF/.
Если вам нужна интернационализация ваших JSP-файлов, рекомендуется, чтобы вы располагали JSP-файлы на различных языках в различных, отведенных под каждую из локалей директориях. Например, версия JSP-страницы index.jsp на US English должна была бы располагаться в /en_US/, тогда как японская версия этой же страницы — в /ja_JP/.
Структура организации файлов
Хорошо структурированный исходный код не только намного проще читать, в нем также можно быстрее найти необходимую информацию в пределах какого-либо файла. В этой части статьи мы рассмотрим структуру файлов JSP и TLD (Tag Library Descriptor).
JSP- и JSPF-файлы
JSP-файл состоит из следующих секций:
1. Начальный комментарий.
2. Директивы JSP-страницы.
3. Директивы библиотеки тэгов (опционально).
4. Различные JSP-объявления (опционально).
5. HTML- и JSP-код.
Теперь мы разберем каждую из этих секций в отдельности.
Начальный комментарий
Всякий JSP-файл или его фрагмент начинается с комментария, который имеет следующий вид:
<%--
- Author(s):
- Date:
- Copyright Notice:
- @(#)
- Description:
--%>
Этот комментарий виден только на стороне сервера, т.е. не передается клиенту-пользователю, поскольку автоматически обрезается при обработке JSP-транслятором web-контейнера. Поля Имя автора(ов) (Author(s)), Дата (Date), Информация об авторских правах (Copyright Notice) и Описание (Description) заполняются непосредственно web-разработчиком. Комбинация же символов "@(#)" обычно распознается программами как индикатор начала идентификатора. Поскольку подобные программы используются не так уж и часто, это поле использовать необязательно. Кстати, иногда в комментарий добавляют также комбинацию символов "$Id$" для идентификационной информации, которую автоматически добавляют многие программы, которые ведут контроль над версией программы (CVS). Поле Description обычно содержит дополнительную информацию о предназначении конкретной JSP-страницы. Обычно оно не занимает более одного параграфа.
В некоторых случаях возникает необходимость использования начального комментария, который оставался бы после трансляции и был доступен клиенту-пользователю для того, чтобы довести до него какую-либо информацию (например, о легальности использования содержимого этой страницы). Этого можно добиться, разбив комментарий на две части: первый для клиентской стороны:
<!--
- Author(s):
- Date:
- Copyright Notice:
--%>
а второй — для серверной (недоступный для клиента):
<%--
- @(#)
- Description:
--%>
Директивы JSP-страницы
Директивы JSP-страницы определяют атрибуты, которые ассоциируются с процессом трансляции JSP. В спецификации JSP не определено максимальное количество директив, которое может быть определено в одном элементе page, поэтому рассмотрим два варианта, которые, в сущности, эквивалентны:
Пример 1
<%@ page session="false" %>
<%@ page import="java.util.*" %>
<%@ page errorPage="/common/errorPage.jsp" %>
Если длина какой-то строки превышает нормальную для JSP-страниц длину в 80 символов, директива разбивается на несколько строчек, как, например:
Пример 2
<%@ page session="false"
import="java.util.*"
errorPage="/common/errorPage.jsp"
%>
В целом второй пример предпочтительнее, чем первый. Исключение составляет случай, когда в JSP нужно включить множество различных Java-пакетов, что может привести к предельно длинному определению атрибута import:
<%@ page session="false"
import="java.util.*,java.text.*,
com.mycorp.myapp.taglib.*,
com.mycorp.myapp.sql.*, ..."
...
%>
Чтобы решить эту проблему, мы можем разбить определение этой директивы в несколько строк, например:
<%-- все атрибуты исключая import --%>
<%@ page
...
%>
<%-- здесь начинается определение атрибутов import --%>
<%@ page import="java.util.*" %>
<%@ page import="java.text.*" %>
...
Директивы библиотеки тэгов (опциально)
Директива библиотеки тэгов позволяет объявлять пользовательские тэги, которые предполагается использовать в этой JSP-странице. Приведем пример:
<%@ taglib uri="URI1" prefix="tagPrefix1" %>
<%@ taglib uri="URI2" prefix="tagPrefix2" %>
...
Точно так же, как и с директивой page, директива taglib может быть разбита на несколько строк:
<%@ taglib
uri="URI2"
prefix="tagPrefix2"
%>
Начиная с JSP версии 1.2 рекомендуется пользоваться стандартной библиотекой тэгов (JSP Standard Tag Library, JSTL, http://java.sun.com/products/jsp/jstl/index.html ) в вашем web-приложении, чтобы пресечь необходимость использования JSP-скриптлетов на ваших страницах. Страницы, которые используют JSTL, обычно гораздо проще читать, а также обеспечивать их дальнейшую поддержку.
Различные JSP-объявления (опциально)
С помощью JSP-объявлений можно объявлять методы и переменные, принадлежащие конкретной JSP-странице. Эти методы и переменные абсолютно ничем не отличаются от тех, которые объявляются в Java-приложениях. Предпочтительно, чтобы код этих объявлений располагался в одном блоке <%!... %>, чтобы сконцентрировать все объявления в определенном месте JSP-страницы. Например:
<%!
private int hitCount;
private Date today;
public int getHitCount() {
return hitCount;
}
%>
HTML- и JSP-код
Эта секция JSP-страницы содержит HTML-код, а также JSP-код: JSP-выражения, скриптлеты и JavaBeans-инструкции.
TLD-файлы
TLD (Tag Library Descriptor) должен начинаться с правильного XML-объявления и DTD. Например, TLD в JSP 1.2 должен начинаться следующим образом:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
PUBLIC "-//Sun Microsystems, Inc.// DTD JSP Tag Library 1.2//EN"
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
Сразу за этим следует все тот же комментарий, что и в JSP-файлах. Все поля полностью соответствуют своим аналогам в JSP-файлах. Поле Description по-прежнему не должно быть очень длинным (в пределах одного параграфа) и должно содержать информацию о библиотеке.
Правила и соглашения, применяемые к TLD-файлам, фактически полностью соответствуют рассмотренным нами выше для JSP-файлов и фрагментов.
Оставшаяся часть TLD-файла обычно состоит из следующих секций:
1. Объявление одного TLF (Tag Library Validator) (опциально).
2. Объявление обработчиков ("слушателей") событий (опциально).
3. Объявление одного или более доступных тэгов.
Рекомендуется всегда добавлять в TLD-элементы следующие опциальные подэлементы. Эти подэлементы дают возможность разработчикам тэгов оставлять пометки, описания и прочую полезную дополнительную информацию о данном TLD, позволяя другим web-разработчикам быстрее разобраться с ним. Вот таблица названных подэлементов:
Отступы
Все отступы должны быть заполнены пробелами. Символы табуляции по-разному интерпретируются различными редакторами и не должны использоваться для отступов внутри JSP-страниц. Номинал отступа обычно составляет 4 пробела. Например:
<myTagLib:forEach var="client" items= "${clients}">
<myTagLib:mail value="${client}" />
</myTagLib:forEach>
Если для выравнивания какого-либо участка кода необходимо более 4-х пробелов, то используется множество номинальных отступов по 4 пробела, например:
<%@ page attribute1="value1"
attribute2="value2"
...
attributeN="valueN"
%>
Отступы в скриптовых элементах
В случае, когда JSP-элемент (как, например, объявление, выражение или скриптлет) не умещается в одну строку, применяется соглашение об отступах в скриптовых языках к телу этого элемента. Тело элемента начинается со следующей строки после символов <%= и заканчивается символами %> . Приведем пример:
<%= (Calendar.getInstance().get(Cale-ndar.DAY_OF_WEEK)
= Calendar.SUNDAY) ?
"Sleep in" :
"Go to work"
%>
Черным цветом обозначены те места, где необходимо применить номинальный отступ в этом случае.
Составные отступы в JSP, HTML и Java
Составные отступы для JSP-элементов, перемешанных с Java-кодом и текстом шаблонов HTML, необходимы для того, чтобы сделать такой составной JSP-код более понятным, поскольку использование лишь правила, рассмотренного выше, сделает исходный код JSP-страницы очень сложным и запутанным. Основное правило составного отступа предельно просто — вставлять дополнительный номинальный отступ (4 пробела) между всеми элементами (JSP, Java или HTML), встречающимися внутри других. Понятно, что такие изменения не приведут к каким-то нежелательным последствиям в отображении результата в браузере пользователя. Итак, вставляя дополнительные отступы в свой код, мы делаем его более читабельным:
<table>
<% if { tableHeaderRequired ) { %>
<tr>
<th> Last Name</th>
<th> First Name</th>
</tr>
<% } %>
<c:forEach var="customer" items="$ {customers}">
<tr>
<td> <c:out value="${customer. lastName}"/> </td>
<td> <c:out value="${customer. firstName}"/> </td>
</tr>
</c:forEach>
</table>
чем вот этот:
<table>
<% if { tableHeaderRequired ) { %>
<tr>
<th> Last Name</th>
<th> First Name</th>
</tr>
<% } %>
<c:forEach var="customer" items="$ {customers}">
<tr>
<td> <c:out value="${customer. lastName}"/> </td>
<td> <c:out value="${customer.fi rstName}"/> </td>
</tr>
</c:forEach>
</table>
Комментарий
Комментарий используется для добавления дополнительной информации и предполагаемых целях близлежащего исходного кода.
Ниже мы рассмотрим два вида комментариев в JSP-файлах: JSP-комментарий и комментарий, доступный клиенту (HTML).
JSP-комментарий
Комментарий JSP (его также иногда называют серверным комментарием) недоступен клиентской стороне. Такой комментарий может быть двух видов: комментарий внутри блока скриптлета или же родной JSP-комментарий. Конечно, предпочтительнее использовать последний. Следующая таблица иллюстрирует возможные варианты JSP-комментария:
Такой комментарий (<!--... --> ) удобно использовать в случае, когда при ответе клиенту нужно каким-то образом обозначить некоторые места ответной страницы дополнительной информацией. Эта информация не должна содержать каких бы то ни было технических особенностей самого приложения или, того хуже, исходного кода.
В принципе, использование этого комментария не очень-то и необходимо, поскольку, если пользователь не захочет получить эту информацию, заключенную в комментарий, он ее не получит. Исключение составляет включение информации о легальности использования информации и авторских правах. Подобного рода информацию следует включать всегда, если передаваемая пользователю информация имеет какую-то ценность. Другим исключением из общего правила можно назвать те комментарии, которые используют авторы HTML, чтобы отметить места расположения различных таблиц, управляющих меню и прочего в HTML-документе для того, чтобы впоследствии можно было легко разобраться, где что, например:
<!-- toolbar section -->
...
<!-- left-hand side navigation bar -->
...
<!-- main body -->
...
<!-- footer -->
...
Если вам нужно использовать многострочные комментарии, то очень удобно каждую строку тела комментария начинать с символа "-". Поскольку "--" не удовлетворяет спецификации XML, лучше предпочесть "-". Пример:
<!--
- line 1
- line 2
...
-->
В следующей статье мы рассмотрим соглашения, принятые для написания кода JSP-объявлений, скриптлетов, выражений, обсудим именные соглашения, форматирование XML-кода внутри JSP-страниц, а также затронем особенности использования JavaBeans, JavaScript, CSS и других технологий совместно с JSP.
По материалам Kam Hay Fung и Mark Roth
Подготовил Алексей Литвинюк, http://www.litvinuke.hut.ru
Поскольку JSP (JavaServer Pages) очень широко применяется во всем мире для написания web-приложений, многие JSP-программисты и web-разработчики, которые начинают разрабатывать и поддерживать подобные приложения, сталкиваются с той же проблемой, что и многие Java-разработчики: "Как нам структурировать JSP-код таким образом, чтобы его было легко читать, писать, а также обеспечить дальнейшую поддержку реализованного приложения?" В этой статье мы рассмотрим набор стандартных соглашений для написания JSP-страниц и приложений (версии JSP 1.1 и 1.2), которых было бы полезно придерживаться и при разработке типичных программных проектов, использующих web-компоненты.
Существующая на данный момент версия JSP 2.0 ( http://jcp.org/en/jsr/detail?id=152 ), практически полностью совместимая с 1.2, предоставляет разработчикам совершенно новый стиль в программировании web-приложений (без определений, скриптлетов и выражений) и имеет ряд новых особенностей, к которым также отчасти могут быть применены рассмотренные здесь соглашения.
Предполагается, что вы знакомы с JSP и Java.
Зачем вообще нужны соглашения в коде?
Кодовые соглашения важны и должны применяться программистами и web-разработчиками по ряду причин:
1. Они улучшают читабельность программных артефактов (под артефактами понимаются программные элементы разрабатываемого приложения).
2. Они позволяют уменьшить затраты усилий на управление проектом.
3. Они выводят ваш код на новый уровень, и он подпадает под общепринятые стандарты.
Имена файлов и их расположение
Именование файлов позволяет инструментами и web-контейнерами различных производителей определять типы файлов и интерпретировать их надлежащим образом. Следующая таблица представляет список рекомендаций по именованию и расположению разного рода файлов, используемых при написании web-приложений:
Тип файла | Суффикс файла | Рекомендованное расположение файла |
JSP | .jsp | <context root>/<subsystem path>/ |
Фрагмент JSP | .jsp | <context root>/<subsystem path>/ |
.jspf | <context root>/WEB-INF/jspf/<subsystem path>/ | |
Каскадная таблица стилей (CSS) | .css | <context root>/css/ |
JavaScript | .js | <context root>/js/ |
HTML-страница | .html | <context root>/<subsystem path>/ |
Web-ресурс | .gif, .jpg, и пр. | <context root>/images/ |
Описатель библиотеки тэгов | .tld | <context root>/WEB-INF/tld/ |
Первое: <context root> — это корневой путь к директории, в которой располагается разрабатываемое вами web-приложение (корневая директория внутри .war-файла).
Второе: <subsystem path> — используется для логического разделения и группировки динамических и статических web-страниц. Для небольших web-приложений этот параметр может быть пустой строкой.
Третье: под JSP-фрагментом понимается какой-то JSP-код, который впоследствии может быть включен в другую JSP-страницу. JSP-фрагменты могут именоваться, как это видно из таблицы, как с суффиксом .jsp, так и с суффиксом .jspf и должны быть расположены либо в директории /WEB-INF/jspf, либо в одной директории со статическим содержимым соответственно. Те JSP-фрагменты, которые не представляют собой полноценной web-страницы, всегда должны именоваться с суффиксом .jspf и размещаться в /WEB-INF/jspf.
Наконец, всегда желательно располагать файлы — описатели библиотеки тэгов (tag library descriptor) и прочие не предназначенные для пользователей файлы в директории WEB-INF/ или в какой-нибудь из ее поддиректорий, поскольку в таком случае содержимое этих файлов будет недоступно для клиентов-пользователей, т.к. никакой из web-контейнеров не будет выдавать по запросу никаких файлов из WEB-INF/.
Если вам нужна интернационализация ваших JSP-файлов, рекомендуется, чтобы вы располагали JSP-файлы на различных языках в различных, отведенных под каждую из локалей директориях. Например, версия JSP-страницы index.jsp на US English должна была бы располагаться в /en_US/, тогда как японская версия этой же страницы — в /ja_JP/.
Структура организации файлов
Хорошо структурированный исходный код не только намного проще читать, в нем также можно быстрее найти необходимую информацию в пределах какого-либо файла. В этой части статьи мы рассмотрим структуру файлов JSP и TLD (Tag Library Descriptor).
JSP- и JSPF-файлы
JSP-файл состоит из следующих секций:
1. Начальный комментарий.
2. Директивы JSP-страницы.
3. Директивы библиотеки тэгов (опционально).
4. Различные JSP-объявления (опционально).
5. HTML- и JSP-код.
Теперь мы разберем каждую из этих секций в отдельности.
Начальный комментарий
Всякий JSP-файл или его фрагмент начинается с комментария, который имеет следующий вид:
<%--
- Author(s):
- Date:
- Copyright Notice:
- @(#)
- Description:
--%>
Этот комментарий виден только на стороне сервера, т.е. не передается клиенту-пользователю, поскольку автоматически обрезается при обработке JSP-транслятором web-контейнера. Поля Имя автора(ов) (Author(s)), Дата (Date), Информация об авторских правах (Copyright Notice) и Описание (Description) заполняются непосредственно web-разработчиком. Комбинация же символов "@(#)" обычно распознается программами как индикатор начала идентификатора. Поскольку подобные программы используются не так уж и часто, это поле использовать необязательно. Кстати, иногда в комментарий добавляют также комбинацию символов "$Id$" для идентификационной информации, которую автоматически добавляют многие программы, которые ведут контроль над версией программы (CVS). Поле Description обычно содержит дополнительную информацию о предназначении конкретной JSP-страницы. Обычно оно не занимает более одного параграфа.
В некоторых случаях возникает необходимость использования начального комментария, который оставался бы после трансляции и был доступен клиенту-пользователю для того, чтобы довести до него какую-либо информацию (например, о легальности использования содержимого этой страницы). Этого можно добиться, разбив комментарий на две части: первый для клиентской стороны:
<!--
- Author(s):
- Date:
- Copyright Notice:
--%>
а второй — для серверной (недоступный для клиента):
<%--
- @(#)
- Description:
--%>
Директивы JSP-страницы
Директивы JSP-страницы определяют атрибуты, которые ассоциируются с процессом трансляции JSP. В спецификации JSP не определено максимальное количество директив, которое может быть определено в одном элементе page, поэтому рассмотрим два варианта, которые, в сущности, эквивалентны:
Пример 1
<%@ page session="false" %>
<%@ page import="java.util.*" %>
<%@ page errorPage="/common/errorPage.jsp" %>
Если длина какой-то строки превышает нормальную для JSP-страниц длину в 80 символов, директива разбивается на несколько строчек, как, например:
Пример 2
<%@ page session="false"
import="java.util.*"
errorPage="/common/errorPage.jsp"
%>
В целом второй пример предпочтительнее, чем первый. Исключение составляет случай, когда в JSP нужно включить множество различных Java-пакетов, что может привести к предельно длинному определению атрибута import:
<%@ page session="false"
import="java.util.*,java.text.*,
com.mycorp.myapp.taglib.*,
com.mycorp.myapp.sql.*, ..."
...
%>
Чтобы решить эту проблему, мы можем разбить определение этой директивы в несколько строк, например:
<%-- все атрибуты исключая import --%>
<%@ page
...
%>
<%-- здесь начинается определение атрибутов import --%>
<%@ page import="java.util.*" %>
<%@ page import="java.text.*" %>
...
Директивы библиотеки тэгов (опциально)
Директива библиотеки тэгов позволяет объявлять пользовательские тэги, которые предполагается использовать в этой JSP-странице. Приведем пример:
<%@ taglib uri="URI1" prefix="tagPrefix1" %>
<%@ taglib uri="URI2" prefix="tagPrefix2" %>
...
Точно так же, как и с директивой page, директива taglib может быть разбита на несколько строк:
<%@ taglib
uri="URI2"
prefix="tagPrefix2"
%>
Начиная с JSP версии 1.2 рекомендуется пользоваться стандартной библиотекой тэгов (JSP Standard Tag Library, JSTL, http://java.sun.com/products/jsp/jstl/index.html ) в вашем web-приложении, чтобы пресечь необходимость использования JSP-скриптлетов на ваших страницах. Страницы, которые используют JSTL, обычно гораздо проще читать, а также обеспечивать их дальнейшую поддержку.
Различные JSP-объявления (опциально)
С помощью JSP-объявлений можно объявлять методы и переменные, принадлежащие конкретной JSP-странице. Эти методы и переменные абсолютно ничем не отличаются от тех, которые объявляются в Java-приложениях. Предпочтительно, чтобы код этих объявлений располагался в одном блоке <%!... %>, чтобы сконцентрировать все объявления в определенном месте JSP-страницы. Например:
<%!
private int hitCount;
private Date today;
public int getHitCount() {
return hitCount;
}
%>
HTML- и JSP-код
Эта секция JSP-страницы содержит HTML-код, а также JSP-код: JSP-выражения, скриптлеты и JavaBeans-инструкции.
TLD-файлы
TLD (Tag Library Descriptor) должен начинаться с правильного XML-объявления и DTD. Например, TLD в JSP 1.2 должен начинаться следующим образом:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib
PUBLIC "-//Sun Microsystems, Inc.// DTD JSP Tag Library 1.2//EN"
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
Сразу за этим следует все тот же комментарий, что и в JSP-файлах. Все поля полностью соответствуют своим аналогам в JSP-файлах. Поле Description по-прежнему не должно быть очень длинным (в пределах одного параграфа) и должно содержать информацию о библиотеке.
Правила и соглашения, применяемые к TLD-файлам, фактически полностью соответствуют рассмотренным нами выше для JSP-файлов и фрагментов.
Оставшаяся часть TLD-файла обычно состоит из следующих секций:
1. Объявление одного TLF (Tag Library Validator) (опциально).
2. Объявление обработчиков ("слушателей") событий (опциально).
3. Объявление одного или более доступных тэгов.
Рекомендуется всегда добавлять в TLD-элементы следующие опциальные подэлементы. Эти подэлементы дают возможность разработчикам тэгов оставлять пометки, описания и прочую полезную дополнительную информацию о данном TLD, позволяя другим web-разработчикам быстрее разобраться с ним. Вот таблица названных подэлементов:
TLD-элемент | JSP 1.2, подэлементы, рекомендованные к определению | JSP 1.1, подэлементы, рекомендованные к определению |
attribute (JSP 1.2) | description | — |
init-param (JSP 1.2) | description | — |
tag | display-name, description, example | name, info |
taglib | uri, display-name, description | uri, info |
validator (JSP 1.2) | description | — |
variable (JSP 1.2) | description | — |
Все отступы должны быть заполнены пробелами. Символы табуляции по-разному интерпретируются различными редакторами и не должны использоваться для отступов внутри JSP-страниц. Номинал отступа обычно составляет 4 пробела. Например:
<myTagLib:forEach var="client" items= "${clients}">
<myTagLib:mail value="${client}" />
</myTagLib:forEach>
Если для выравнивания какого-либо участка кода необходимо более 4-х пробелов, то используется множество номинальных отступов по 4 пробела, например:
<%@ page attribute1="value1"
attribute2="value2"
...
attributeN="valueN"
%>
Отступы в скриптовых элементах
В случае, когда JSP-элемент (как, например, объявление, выражение или скриптлет) не умещается в одну строку, применяется соглашение об отступах в скриптовых языках к телу этого элемента. Тело элемента начинается со следующей строки после символов <%= и заканчивается символами %> . Приведем пример:
<%= (Calendar.getInstance().get(Cale-ndar.DAY_OF_WEEK)
= Calendar.SUNDAY) ?
"Sleep in" :
"Go to work"
%>
Черным цветом обозначены те места, где необходимо применить номинальный отступ в этом случае.
Составные отступы в JSP, HTML и Java
Составные отступы для JSP-элементов, перемешанных с Java-кодом и текстом шаблонов HTML, необходимы для того, чтобы сделать такой составной JSP-код более понятным, поскольку использование лишь правила, рассмотренного выше, сделает исходный код JSP-страницы очень сложным и запутанным. Основное правило составного отступа предельно просто — вставлять дополнительный номинальный отступ (4 пробела) между всеми элементами (JSP, Java или HTML), встречающимися внутри других. Понятно, что такие изменения не приведут к каким-то нежелательным последствиям в отображении результата в браузере пользователя. Итак, вставляя дополнительные отступы в свой код, мы делаем его более читабельным:
<table>
<% if { tableHeaderRequired ) { %>
<tr>
<th> Last Name</th>
<th> First Name</th>
</tr>
<% } %>
<c:forEach var="customer" items="$ {customers}">
<tr>
<td> <c:out value="${customer. lastName}"/> </td>
<td> <c:out value="${customer. firstName}"/> </td>
</tr>
</c:forEach>
</table>
чем вот этот:
<table>
<% if { tableHeaderRequired ) { %>
<tr>
<th> Last Name</th>
<th> First Name</th>
</tr>
<% } %>
<c:forEach var="customer" items="$ {customers}">
<tr>
<td> <c:out value="${customer. lastName}"/> </td>
<td> <c:out value="${customer.fi rstName}"/> </td>
</tr>
</c:forEach>
</table>
Комментарий
Комментарий используется для добавления дополнительной информации и предполагаемых целях близлежащего исходного кода.
Ниже мы рассмотрим два вида комментариев в JSP-файлах: JSP-комментарий и комментарий, доступный клиенту (HTML).
JSP-комментарий
Комментарий JSP (его также иногда называют серверным комментарием) недоступен клиентской стороне. Такой комментарий может быть двух видов: комментарий внутри блока скриптлета или же родной JSP-комментарий. Конечно, предпочтительнее использовать последний. Следующая таблица иллюстрирует возможные варианты JSP-комментария:
| Тип комментария | JSP-скриптлет со вставленным внутрь комментарием | Родной JSP-комментарий |
| однострочный | <% /** ... */ %> <% /* ... */ %> <% // ... %> | <%-- ... --%> |
| многострочный | <% /* * ... * */ %> | <%-- - ... - -- %> |
| <% // // ... // %> |
Такой комментарий (<!--... --> ) удобно использовать в случае, когда при ответе клиенту нужно каким-то образом обозначить некоторые места ответной страницы дополнительной информацией. Эта информация не должна содержать каких бы то ни было технических особенностей самого приложения или, того хуже, исходного кода.
В принципе, использование этого комментария не очень-то и необходимо, поскольку, если пользователь не захочет получить эту информацию, заключенную в комментарий, он ее не получит. Исключение составляет включение информации о легальности использования информации и авторских правах. Подобного рода информацию следует включать всегда, если передаваемая пользователю информация имеет какую-то ценность. Другим исключением из общего правила можно назвать те комментарии, которые используют авторы HTML, чтобы отметить места расположения различных таблиц, управляющих меню и прочего в HTML-документе для того, чтобы впоследствии можно было легко разобраться, где что, например:
<!-- toolbar section -->
...
<!-- left-hand side navigation bar -->
...
<!-- main body -->
...
<!-- footer -->
...
Если вам нужно использовать многострочные комментарии, то очень удобно каждую строку тела комментария начинать с символа "-". Поскольку "--" не удовлетворяет спецификации XML, лучше предпочесть "-". Пример:
<!--
- line 1
- line 2
...
-->
В следующей статье мы рассмотрим соглашения, принятые для написания кода JSP-объявлений, скриптлетов, выражений, обсудим именные соглашения, форматирование XML-кода внутри JSP-страниц, а также затронем особенности использования JavaBeans, JavaScript, CSS и других технологий совместно с JSP.
По материалам Kam Hay Fung и Mark Roth
Подготовил Алексей Литвинюк, http://www.litvinuke.hut.ru
Компьютерная газета. Статья была опубликована в номере 10 за 2003 год в рубрике программирование :: разное
