Какие разделительные линии в коде вы используете?

[Hummerstadt]

Какие разделительные линии в коде вы используете?

Что вы используете для отделения или выделения определения функций, например?
Я сейчас такое,

/************ function get_results ************/
function get_results()
/************ end ************/

однако такие рамки при быстрой прокрутке почти не заметны, и плюс несимметричные.
Печатать больше звездочек долго.
Что используете вы?

 

[BOJIK]

Re: Какие разделительные линии в коде вы используете?

Hummerstadt
Зачем писать в комментарии function get_results когда и так (кому надо) видит что это функция и как она называется?
Поэтому я использую разделитель (если это можно назвать разделитель) в стиле phpdoc. Чтото типа такого

/**
 * Здесь цель функции(метода)
 *
 * @param mixed $var
 * @param mixed $val
 */
function assign($var, $val);

подробнее читать тут

 

[iliah]

ну и сразу критика phpdoc, в частности собственно форматирования

Hummerstadt
> Печатать больше звездочек долго.
к примеру, в виме проблема решается через
:ab #b /*** <сколько угодно символов> ***
:ab #e ****<сколько угодно символов> ***/

далее после набора #b<пробел> получаете "длинный" коммент

 

[Hummerstadt]

Re: Re: Какие разделительные линии в коде вы используете?

Автор оригинала: BOJIK
Зачем писать в комментарии function get_results когда и так (кому надо) видит что это функция и как она называется?

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

 

[BOJIK]

Hummerstadt
1. Как это тебе поможет в поиске если коммент стоит рядом с определением функции? Зачем писать два раза одно и тоже?
2. Еще приятней открыть и понять назначение функции. Что делает get_results из названия не очень понятно надо лезть в код.
3. Тогда без документации, в которой не только названия твоей функции, но и аргументы и типы выходных значений не обойтись. А еще хорошо бы чтобы это дело можно было собрать в готовую доку для сторонних разработчиков, которым вероятно меньше всего (сужу по себе) хочеться лазить по твоему коду с красивыми, но абсолютно бесполезными комментариями.

 

[Hummerstadt]

Автор оригинала: BOJIK
Hummerstadt
1. Как это тебе поможет в поиске если коммент стоит рядом с определением функции? Зачем писать два раза одно и тоже?

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

2. Еще приятней открыть и понять назначение функции. Что делает get_results из названия не очень понятно надо лезть в код.

Если вы так делаете, могу посоветовать в шапки выделенного блока с (объявлением функции), описать входные и выходные данные на свой вкус.

3. Тогда без документации, в которой не только названия твоей функции, но и аргументы и типы выходных значений не обойтись. А еще хорошо бы чтобы это дело можно было собрать в готовую доку для сторонних разработчиков, которым вероятно меньше всего (сужу по себе) хочеться лазить по твоему коду с красивыми, но абсолютно бесполезными комментариями.

А вы не одного моего живого комментария в трудах за последнюю неделю не видели.
Они все абсолютно полезные, но не красивые. А документация не исключает комментарии в коде. Готовые решения ищат неопытные товарищи, для них коммент - золото. Проверено на себе.

 

[BOJIK]

Hummerstadt
Я придерживаюсь того мнения что за рога в рай не затянешь. Твой код тебе и оформлять в соответсвии с твоими эстетическими потребностями. Я пытался указать на уже готовый велосипед. Хочешь изобрести свой твое право.
ИМХО хорошему коду редко требуются комментарии в коде. По хорошему коду и так видно, что он делает.

 

[Лисю]

Мн не понравился сложный синтаксис phpdoc.

делаю так, как в invision:

//--------------------------------------------
// Require the HTML and language modules
//--------------------------------------------
    	
$ibforums->lang = $std->load_words($ibforums->lang, 'lang_buddy', $ibforums->lang_id );
    	
$this->html = $std->load_template('skin_buddy');

 

[[DAN]]

phpdoc рулит определенно
Также рекомендую к прочтению книгу "Совершенный код" Макконнелла, главы 31-32

 

[BOJIK]

[DAN]
Поддерживаю. Местами очень неплохая книга.

 

[Alexandre]

phpdoc рулит определенно

+1
рекомендую книгу "Рефакторинг: улучшение существующего кода"
http://www.books.ru/shop/search?search_type=+&query=%F0%E5%F4%E0%EA%F2%EE%F0%E8%ED%E3

одно из основных правил рефакторинга "методы должны быть краткими и лаконично-понятно обозначающие их действие, чтоб из названия было понятно, что он делает"

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

извините за оффтоп - но потратив пол дня времени на изучение пхпДок, вы сэкономите много времени в будущем при вспоминании того - что же делает каждый метод...
сделать до

 

[master_x]

есть стандарты кодирования PHP. Можно заглянуть в гугль и все сразу станет ясным.