Комментарии в Java используются для предоставления дополнительной информации о коде, который требует объяснения своего назначения. Даже если вы не планируете, что код вашей модели будут читать и пытаться понять другие пользователи, пишите комментарии для себя, тогда даже если вы продолжите разработку модели спустя пару месяцев, вы сможете легко вспомнить, как она работает, исправить в ней все необходимое или же дополнить ее новыми деталями. Написание хороших комментариев должно войти у вас в привычку.

Вот пример бессмысленного комментария:

client = null; // делаем client равным null — бессмысленный комментарий

Он объясняет то, что и так понятно из кода. Вместо этого вы могли бы объяснить смысл данного присваивания:

client = null; // забываем клиента  —  все операции завершены

В Java есть два типа комментариев: строчный комментарий и блочный комментарий.

Строчный комментарий начинается с двойного символа // (без пробелов между ними) — весь следующий за ним до конца данной строки текст рассматривается Java как комментарий:

// создаем новую фабрику
Plant plant = add_mills();// помещаем ее где-то в выбранном регионе
double[] loc = region.findLocation();
plant.setXY( loc[0], loc[1] );// задаем параметры фабрики
plant.set_region( region );
plant.set_company( this ); // мы являемся владельцем

Java редактор AnyLogic отображает комментарии зеленым цветом, поэтому вы можете легко отличить их от обычного кода.

Блочный комментарий ограничивается символами /* и */. В отличие от строчного комментария, блочный комментарий может быть помещен в середине строки (или даже в середине выражения), а может охватывать несколько строк.

/* выплачиваем менеджерам комиссионные по итогам квартальных продаж */
amount = employee.baseSalary + commissionRate * employee.sales + bonus;
if( amount > 200000 )
  doAudit( employee );
/* проводим аудит для сверхкрупных платежей */
employee.pay( amount );

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

amount = employee.baseSalary + /* commissionRate * employee.sales + */ bonus;

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

while( ! backlog.isEmpty() ) { // repeat the code below while the backlog is not empty
  Order order = backlog.getFirst(); // pick the first order in the backlog
  if( order.amount <= inventory ) { // if enough inventory to satisfy this order //  ship( order ); // ship
    inventory -= order.amount; // decrease available inventory
    backlog.removeFirst(); // remove the order from the backlog
  } else { // not enough inventory to ship
    break; // stop order backlog processing
  }
}

Если исключается несколько строк, то лучше использовать блочный комментарий:

/*
while( ! backlog.isEmpty() ) { // repeat the code below while the backlog is not empty
  Order order = backlog.getFirst(); // pick the first order in the backlog
  if( order.amount <= inventory ) { // if enough inventory to satisfy this order
    // ship( order ); // ship
    inventory -= order.amount; // decrease available inventory
    backlog.removeFirst(); // remove the order from the backlog
  } else { // not enough inventory to ship
    break; // stop order backlog processing
  }
}
*/

Будьте внимательны при исключении кода с помощью комментариев: вы невольно можете внести нежелательные изменения в соседний код. Давайте рассмотрим приведенный ниже фрагмент кода. Изначально планировалось выполнять аудит для каждого платежа, превышающего $200,000. Разработчик модели решил временно не выполнять проверку и закомментировал строку с вызовом функции doAudit(). Побочным эффектом такого действия стало то, что следующая строка кода стала частью оператора if, и платежи в такой модели будут производиться только тем служащим, которые заработали для компании более $200,000.

amount = employee.baseSalary + commissionRate * employee.sales + bonus;
if( amount > 200000 )
  // doAudit( employee );
  employee.pay( amount );

Обратите внимание, что такой неприятной ситуации можно было бы избежать, заключи разработчик модели тело оператора if в фигурные скобки (т.е. сделав его блоком):

amount = employee.baseSalary + commissionRate * employee.sales + bonus;
if( amount < 200000 ) {
  // doAudit( employee );
}
employee.pay( amount );

Как мы можем улучшить эту статью?

Отправить