четверг, 28 августа 2008 г.

Пишите usage для ваших веб-страниц

Часто возникает задача - есть исходник веб-страницы (которую писали черт-те когда), нужно понять, какие параметры она принимает. Чтобы не рыться в исходниках, я для себя давно уже сформировал простое правило - надо в коментариях к странице (классу страницы) описывать все параметры, которые она принимает. Например, так:


///
/// usage:
EditDistributionEmail.aspx?iid=INSTANCE_ID[&back=ENCODED_BACK_URL]
///

public partial class EditDistributionEmail :
System.Web.UI.Page
{

...


С точки зрения программиста, веб-страница ничем не отличается от статической функции - принимает некоторый набор параметров (HTTP Request) и возвращает некоторые значения (HTTP Response).

А следовательно, и документировать ее надо как функциою - описывать параметры и return value (последнее для фанатов, конечно :). Хотя, если страница может менять какие-то глобальные cookies, это желательно в документации тоже указать.

3 комментария:

Vladislav комментирует...
Этот комментарий был удален автором.
Vladislav комментирует...

Эх, молодо-зелено... : )

Как вам декларативное описание необходимых параметров? Не указали необходимый get-параметр (или ошиблись его типом), и страничка вам сама об этом напомнит...

public partial class _Default : CrmPage
{

/// <summary>
/// Пример маппинга значения параметра "id" QueryString страницы в поле "entityID".
/// </summary>
[QueryStringParameter("id")]
public Guid entityID;

private int _entityType;

/// <summary>
/// Пример маппинга значения параметра "type" QueryString страницы в свойство "EntityType".
/// </summary>
[QueryStringParameter("type", IsRequired = true, DefaultValue="1")]
public int EntityType
{
get { return _entityType; }
set { _entityType = value; }
}


/// Источник: статья "Declarative QueryString Parameter Binding"
/// (http://www.codeproject.com/KB/aspnet/WebParameter.aspx)

Yury Skaletskiy комментирует...

декларативное описание QS- это очень круто. из минусов вижу только то, что нельзя описать "перегрузку параметров" - те страничка default.aspx принимает либо ?type=a&id=b
либо ?type=a&name=c

правда, ничто не мешает комбинировать оба варианта в одном.