v8: Рекомендации по оформлению кода 1Сv8
Ключевые слова: Рекомендации, внутренний язык, язык запросов, оформление
Оформление заголовков методов.
В меню контекстной подсказки при наведении мышью на метод отображается только его описание! Т.е. пока не перейдешь к определению самого метода, не узнаешь о его параметрах ничего, если они не будут должным образом описаны в заголовке. В типовых в большинстве случаев заголовок описывает параметры, следуя рекомендациям самой же 1С. И я делал также, но частенько меня расстраивал факт невозможности узнать, является ли параметр метода необходимым и какое значение по умолчанию он имеет. И я решил доработать заголовок метода:
// <Описание функции>
//
// Параметры:
// *<Параметр1> – <Тип.Вид>, *<ЗначениеПоУмолчанию1> – <описание параметра1>
// <продолжение описания параметра1>;
// *<Параметр2> – <Тип.Вид>, *<ЗначениеПоУмолчанию2> – <описание параметра2>
// <продолжение описания параметра2>.
// Возвращаемое значение:
// <Значение1> - <Тип.Вид> – <описание значения1> - <описание условия1>;
// <Значение2> - <Тип.Вид> - <описание значения2> – иначе.
//
Звездочка перед параметром обозначает его необязательность. После звездочки, следующей за типом параметра указывается значение по умолчанию.
Пример
// Получает список реквизитов объекта БД.
//
// Параметры:
// пОбъект – ОбъектБД;
// *СписокВыбора – СписокЗначений, *Неопределено – если нужно заполнить уже имеющийся список;
// *ЛиВключатьТолькоЧитаемые - Булево, *Ложь - включать ли в список только читаемые реквизиты;
// *ЛиВключатьНедоступные - Булево, *Ложь - включать ли в список недоступные (группы/элементы) реквизиты;
// *ЛиСортировать - Булево, *Ложь - отсортировать ли по представлению.
//
// Возвращаемое значение:
// СписокЗначений – содержащий в качестве значений имена реквизитов.
//
|