Комментарии

Комментарии в 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 );