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

Имеется скрипт представляющий собой библиотеку API функций и классов, размером чуть более 1000 строк. Условно его возможно поделить на блоки, согласно задач выполняемых функциями. В процессе разработки каждый блок вынесен в отдельный файл для простоты поиска, после все собирается в отдельный файл.Скрипт имеет открытый исходный код, поэтому хочется сделать его наиболее читаемым.
Теперь суть вопроса: Как наиболее красиво условно разделить файл на блоки с помощью комментариев, чтобы его было удобнее всего читать (не только мне)

-----
if(time()>1356048000) die();

Мне больше всего нравится вариант:

Речь именно об этом.

Еще варианты? Хочется услышать больше мнений.

-----
if(time()>1356048000) die();

-----
ejas-tower@mail.ru

Мне нравится стиль JavaDoc. Логичен, распространён и можно документацию собирать автоматом.

-----
PostgreSQL DBA

Какой таблицы и где?

-----
Шта? Репозиторий?

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

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

-----
if(time()>1356048000) die();

А например когда?

Champion а например в случае production версии фреймворка или ядра cms. в моих разработках колличество строк одного ядра иногда доходит до 1500 - 2000, а ведь это совсем не много...

-----
if(time()>1356048000) die();

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

Champion а какой в этом смысл? ядро само по себе не выполняет действий, лишь объявляет функции и классы, тесно взаимодействующие между собой, и поэтому для нормальной работы необходимо одновременно иметь под рукой их все. выпадание какой либо из них делает неработоспособной всю систему, и по этому можно сказать что ядро это одно целое. ИМХО файлы стоит делить на части только тогда, когда каждая из этих частей может работать без остальных, т.е являться самостоятельной единицей, а делить на части целое, чтобы потом каждый раз все равно собирать их вместе не имеет смысла.
Далее, модулем ядра назовем определенный набор функций, использующих ядро, но не используемых ядром. Т.е. ядро может работать без модуля, модуль без ядра нет. Модули я выношу в отдельные файлы.
П.С. Естественно это не касается процесса разработки. Как я уже сказал в своем первом посте

-----
if(time()>1356048000) die();

http://ru[dot]wikipedia[dot]org/wiki/PHPDoc

http://www.phpdoc[dot]org/

http://ru[dot]wikipedia[dot]org/wiki/PhpDocumentor

-----
Есть в мире две бесконечные вещи - это Вселенная и человеческая глупость. Но насчет первой .. я не уверен.

Ну можно хранить логически разные вещи в разных модулях, а какой-нибудь один главный модуль ядра пусть их все инклюдит.
Смысл - разделить разный по смыслу функционал по отдельным местам. То, что они все не могут существовать друг без друга, не значит, что они все должны быть в одном файле.
Вот. Правильно. А после разработки происходит поддержка как правило, а поддерживать, когда всё свалено в одну кучу не очень удобно по тем же причинам, по которым не удобно разрабатывать, когда свалено в кучу.
Но, в принципе, это не более, чем моя точка зрения, я ее не навязываю.

EuGen Спасибо, то что надо.
Champion Возможно тогда стоит просто иметь 2 версии: production и development, как это часто и делается, так как поддержка может осуществляться сторонними программистами. спасибо, учту ваше мнение

-----
if(time()>1356048000) die();