Комментирование. Как структурировать комментарии

[Zenitchik]

По прочтении очередной неопределенной ценности книги - "VB тестирование и отладка программ", я начал приводить в порядок свои привычки относительно коментирования.
В конце большинства строк (за исключением тривиальных) после 84-го символа (кстати, как посмотреть позицию курсора? А то экран дом и на работе разной ширины - на работе по краю окна меряю, а дома он почти в середине оказывается) пишу смысл строки в терминах абстрактной модели того, что должна программа делать.
В каждой процедуре пишу:
'тип процедуры (свойство / метод / процедура обработки / внутренняя процедура)0
'назначение (это такая проверка, действительно ли нужна эта процедура)
'Входы (те аргументы, которые используются в качестве входов)
'Выходы (возвращаемое значение и аргументы, которые используютяс для возврата значения)
'Используемые переменные модуля (переменные модуля, значения которых нужны для работы процедуры)
'Действие (описание характера изменения переменных модуля в результате работы процедуры)

Еще охота куда-нибудь список используемых процедур воткнуть, чтобы легче согласовать изменения (тогда будет легче составлять требования вертикальной совместимости, которые долны выполняться для всех ее последующих версий процедуры - а некоторые процедуры приходится порой переписыватьна 100%, так что только по коментариям определяю, что она должна делать).

Кроме того, никак не разработаю систему коментариев в заголовке класса.
Ну, с назначением - все понятно. Это такой способ самопроверки: если не смог внятно описать назначение - стоит задуматься, а нужен ли класс вообще. Понятно с описанием сути переменных уровня модуля.
В некоторых классах еще пишу уравнения согласованности, которые должны выполняться до и после работы каждого метода, или уравнения работы, которые использую как подсказку при разработке методов.

Чую, многого не хватает. Хочу добавить ваш опыт к своему. Кто как делает?

[MIT]

Ну, комментирование каждой строки - лишнее (имхо). Я пользуюсь стандартными возможностями описания функция (процедур etc) - если речь едет о .net, то перед функцией пишем ''', где заполняем всю инфу: зачем, чего, как и куда. По-моему этого вполне достаточно.

[Debugger]

Многое то, что ты перечислил (тип процедуры, назначение, параметры, ...) я узнаю по первой строчке процедуры. Если она реально сложная, то я обычно рисую ASCII-графикой в ее начале схему (если с геометрией связано), привожу формулы, пишу краткий алгоритм. Иначе потом можно запутаться.
Твоя система комментариев лучше подходит для огромных разработок (на которые уходит 1-2 года - тогда можно забыть, что писал 4 месяца назад), open-source или совместных работ - чтобы тебе легче было понять чужое, а другим - твое.

[Zenitchik]

Многое то, что ты перречислил (тип процедуры, назначение, параметры, ...) я узнаю по первой строчке процедуры

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

Кроме того, я веду историю отладки в стиле: дата тип проверки - мероприятия после проверки
'Отладка:
'27.09.08 Чтение кода - исправлена система контроля входных значений
'28.09.08 "Черный ящик" - добавлена устойчивость к пустому массиву на входе

Это делается для того, чтобы выявлять изначально неудачные процедуры по слишком длинному логу исправлений.

[iGrok]

84 символа - это как-то много.
Это как-то очень много.

Вообще советуют (х.з. кто и где, но убедился на практике - это действительно удобнее =) ограничивать длину строки 79ю символами. И, если она длиннее, пользоваться переносами строки " _".

[Zenitchik]

84 символа - это экспериментально установленная удобная мне ширина области кода (при разрешении экрана 1024*768 при размещенном слева окне проект-експлорера).
Позиция коментариев выбрана так, чтобы только ' был виден на краю окна, а текст коментариев не загромождал рабочую облать.

[Денис]

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

[Antonariy]

Коментарии - процесс творческий, как и программирование по большему счету. Поэтому излишняя систематизация тоже может навредить. Старайтесь комментировать так, чтобы самим было понятно. Потому что любые правила сначала организуют, а потом начинают ограничивать.

+1
Я свой код практически не комментирую, разве что неочевидные on error resume next'ы и коды ошибок.

[pronto]

(кстати, как посмотреть позицию курсора? А то экран дом и на работе разной ширины - на работе по краю окна меряю, а дома он почти в середине оказывается)

Если вопрос ещё актуален...

[Ramzes]

Я свой код практически не комментирую, разве что неочевидные on error resume next'ы и коды ошибок.

однозначно зря. За мной сейчас только на работе закреплено 5 проектов, которые уже работают, и вещи которые писались 2 года назад, сейчас трудно понимать, а еще через два года я их вообще не пойму...так, что сейчас все комментирую, не каждую строку конечно, но много каментофф.
ЗЫ каменты жгут

[Antonariy]

Мне приходится много работать с чужим кодом, который я научился понимать почти всегда без проблем, так что "вспоминать" мне не надо. Я сразу вижу что к чему. А в своем тем более.

[Zenitchik]

pronto
Спасибо. Я почему-то инстинктивно внизу искал.