http://habrahabr.ru/post/207390/
От себя добавлю. Я ПРЕДПОЧИТАЮ писать такие комментарии:
1. С описанием проблемы.
2. Со ссылкой на ошибку в Bug-Trekker'е.
3. Со ссылкой на тест.
4. Со ссылкой на нетривиальный алгоритм.
5. Документирующие ОСОБЕННОСТИ входа и выхода метода.
6. Документирующие пост- и пред-условия (хотя тут зачастую можно обойтись Assert'ами).
ВСЕ ОСТАЛЬНЫЕ коментарии я считаю - ИЗБЫТОЧНЫМИ и "вредными".
Понятное дело, что "абсолюта" - нет.
И кстати - если мне вдруг "хочется" написать комментарий, то я ПЕРВЫМ ДЕЛОМ думаю о том - "а нельзя ли тут написать Assert". Потом думаю что-то вроде - "а нельзя ли указатель заменить на ссылку". Потом думаю - "можно ли тут написать тест". А потом думаю об изменении наименований.
А потом только пишу комментарий, если другие варианты "не прокатили".
От себя добавлю. Я ПРЕДПОЧИТАЮ писать такие комментарии:
1. С описанием проблемы.
2. Со ссылкой на ошибку в Bug-Trekker'е.
3. Со ссылкой на тест.
4. Со ссылкой на нетривиальный алгоритм.
5. Документирующие ОСОБЕННОСТИ входа и выхода метода.
6. Документирующие пост- и пред-условия (хотя тут зачастую можно обойтись Assert'ами).
ВСЕ ОСТАЛЬНЫЕ коментарии я считаю - ИЗБЫТОЧНЫМИ и "вредными".
Понятное дело, что "абсолюта" - нет.
И кстати - если мне вдруг "хочется" написать комментарий, то я ПЕРВЫМ ДЕЛОМ думаю о том - "а нельзя ли тут написать Assert". Потом думаю что-то вроде - "а нельзя ли указатель заменить на ссылку". Потом думаю - "можно ли тут написать тест". А потом думаю об изменении наименований.
А потом только пишу комментарий, если другие варианты "не прокатили".
Комментариев нет:
Отправить комментарий