Я всегда документирую свой код так, чтобы другие (и я по дороге) могли быстро понять, что происходит. Поэтому я часто задаюсь вопросом, есть ли какие-либо галереи или коллекция комментариев. Любые ссылки или общие предпочтения?
Вот пара, которую я часто использую (в PHP).
В верхней части файла:
// ******************************* INFORMATION ***************************//
// ***********************************************************************//
//
// ** NAME - A description of what the file does.
// **
// ** @author name <[email protected]>
// ** @date date
// ** @access private
// ** @param
// ** @return if a class what object is returned
//
// ***********************************************************************//
// ********************************** START ******************************//
Используется для обозначения группы функций:
// =======================================================================//
// ! A description of what the following functions have in common //
// =======================================================================//
У меня всегда было самое сложное время для поиска по этой теме, поскольку "блок комментариев" или "комментарии кодов" обычно возвращает информацию о написании системы комментариев для блога:)
