Комментарии

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