Имя пользователя:

Пароль:


Список форумов ПРАКТИЧЕСКИЕ ВОПРОСЫ Работа Программирование и IT Просмотров: 809

Элегантное программирование: Комментирование кода


Давим клаву за бабло
  #1
Сообщение 29 Dec 2013, 12:29
Ursego Аватара пользователя
СОЗДАТЕЛЬ ТЕМЫ
Canada, Ontario
Город: Toronto
Стаж: 12 лет 2 месяца 15 дней
Постов: 10707
Лайкнули: 3448 раз
Карма: 33%
СССР: Днепропетровск
Пол: М
Лучше обращаться на: ты
Заход: 12 Sep 2024, 06:51

Комментируйте код если его чтение может вызвать непонимание или хоть какие-то вопросы.

Это нужно не только другим участникам проекта, но и Вам: сейчас-то Вы помните, что имели в виду, но что будет через неделю, месяц, год?

Не создавайте комментарий если в нём нет необходимости.

В это трудно поверить, но я видел комментарий 'Declare variables:' прямо перед объявлением переменных и 'Call function XXX:' перед вызовом функции XXX!

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

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

private decimal calcNewBalance (integer customerID, decimal amountToAdd)
   {
   // Validate parameters:
   
   // Retrieve existing balance of customer:
         
   // Retrieve their allowed overdraft:
         
   // Calculate new balance:
         
   // If new balance exceeds allowed overdraft then return original balance:
         
   // If this code reached then new amount is ok - return it:

   }

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

  #2     Элегантное программирование: Комментирование кода
Сообщение 29 Dec 2013, 13:01
Cth Аватара пользователя
Canada, British Columbia
Город: Vancouver
Стаж: 10 лет 10 месяцев 15 дней
Постов: 1550
Лайкнули: 312 раз
Карма: 21%
Пол: М
Заход: 09 Aug 2022, 19:36

мне еще нравятся приколы в камментах, да я и сам люблю оставлять какие-то шутки безобидные в камментах, просто чтобы человеку было веселей код читать:
Изображение

//
// Дорогой мейнтейнер:
//
// Когда ты закончишь «оптимизировать» эту подпрограмму
// и поймешь, насколько большой ошибкой было делать это,
// пожалуйста, увеличь счетчик внизу как предупреждение
// для следующего парня:
//
// total_hours_wasted_here = 42
//


// Когда я начинал это писать, только Бог и я понимали, что я делаю
// Сейчас остался только Бог


// иногда мне кажется, что компилятор игнорирует все мои комментарии


// пьян, исправить позже


// Магия. Не трогать.


#define TRUE FALSE
// Удачного дебаггинга, молокососы


<!-- Here be dragons  -->


// I'm sorry.


// I am not sure if we need this, but too scared to delete.


//Please work


   
// I am not responsible of this code.
// They made me write it, against my will.

Вам есть что сказать по этой теме? Зарегистрируйтесь, и сможете оставлять комментарии
cron