Удобочитаем ли следующий код?

← →
codeCleaner (2006-12-07 10:05) [0]

public class ProcessServiceDefault implements ProcessService { /** * Method annotation: * 1. Get list of orders where property "reservationEndDate" less than or equal to parameter "pDate" * 2. For resources, linked to that orders, set state to "free" * 3. For selected orders set state to "off" */ public void freeResources( Date pDate, Session session ) throws NBException { // query for select required orders String orderQuery = "select no " + " from itsm_orders " + " where ( reservation_end_date <= :pDate ) and " + " ( workflow_state_no = :pState )"; Object[] orderParams; // parameters for orders select query SQLDataSet orderList; // list of orders OrderObject orderObject; // instance of order object OrderService orderService; // instance of order service String orderTypeName = "Order"; // name of order type String orderPackageName = "nb.itsm.order"; String stateReserved = "RSV"; // code of reserved state String stateOff = "ORJ"; // code of off state String stateFree = "CRT"; // code of free state BigDecimal stateReservedNo; // no of reserved state BigDecimal stateOffNo; // no of off state BigDecimal stateFreeNo; // no of free state Integer i; // cycle counter ResourceList resourceList; // list of resources, linked to current order ResourcelanObject resourcelanObject; // instance of resource object ResourceLanService resourcelanService; // instance of resource service String resourceTypeName = "ResourceLan"; // name of resource type String resourcelanPackageName = "nb.res.resourceLan"; ObjectServiceDefault objectService; // instance of object service TypeWorkflowStateService workflowStateService; // instance of workflowstate service String workflowStatePackageName = "nb.krn.typeWorkflowState"; // creating and initialization of object service instance objectService = new ObjectServiceDefault(); objectService.setSession( session ); objectService.init(); // creating and initialization of workflowstate service instance workflowStateService = ( TypeWorkflowStateService ) session.getService( workflowStatePackageName ); // creating and initialization of order service instance orderService = ( OrderService ) session.getService( orderPackageName ); // creating and initialization of resource service instance resourcelanService = ( ResourceLanService ) session.getService( resourcelanPackageName ); // getting No for following states stateReservedNo = workflowStateService.codeToNo( objectService.typeNameToNo( orderTypeName ), stateReserved ) ; stateOffNo = workflowStateService.codeToNo( objectService.typeNameToNo( orderTypeName ), stateOff ); stateFreeNo = workflowStateService.codeToNo( objectService.typeNameToNo( resourceTypeName ), stateFree ); orderParams = new Object[] { pDate, stateReservedNo }; // fill query parameters orderList = objectService.executeSelect( orderQuery, orderParams ); // get list of orders // if list of orders is empty then exit if ( orderList.isEOF() ) { orderList.close(); return; } orderList.first(); // go to first record // orders processing while ( ! orderList.isEOF() ) { orderObject = orderService.fetchOrder( orderList.getBigDecimal( 0 ) ); // fetch current order resourceList = orderService.fetchResourceList( orderObject.getNo() ); // get list of resources, linked to current order // resources processing for ( i = 0; i < resourceList.size(); i++ ) { // fetch current resource, set state to free and save changed resource resourcelanObject = resourcelanService.fetchResourcelan( ( resourceList.getResource( i ) ).getResourceNo() ); resourcelanObject.setWorkflowStateNo( stateFreeNo ); resourcelanService.saveResourcelan( resourcelanObject ); } orderObject.setWorkflowStateNo( stateOffNo ); // set order state to off orderService.saveOrder( orderObject ); // save changed order orderList.next(); // try to fetch next record } orderList.close(); } // freeResources - end of body }

← →
codeCleaner (2006-12-07 10:07) [1]

Ну, тут, понятно, все поползло немного...

← →
TUser © (2006-12-07 10:10) [2]

Нет, потому что это не код, а комментарии с небольшой примесью кода. Имхо.

← →
codeCleaner (2006-12-07 10:11) [3]

А как же извечные сетования на то, что через полгода без комментов даже в своем коде разобраться трудов стоит?

← →
TUser © (2006-12-07 10:17) [4]

Вот это, например, чем тебе поможет? При том, что тот факт, что i является цикль каунтером ты и так увидишь при минимальном знакомстве с синтаксисом.

Integer i; // cycle counter

← →
ИА (2006-12-07 10:20) [5]

Комментирование процесса ради еще хуже чем просто отсутствие комментариев ибо ведет к загрязнению кода и излишней трате времени.

← →
codeCleaner (2006-12-07 10:20) [6]

ну, не всегда... встречал коды, в которых прогеры, видимо, жалели непостоянно занятую i и до/после использования ее как счетчик цикла применяли для чего-либо другого...

← →
isasa © (2006-12-07 10:21) [7]

TUser © (07.12.06 10:17) [4]
:)
Integer CycleCounter; // cycle counter

← →
ИА (2006-12-07 10:24) [8]

Собственно все что нужно оставить это шапку над методом.
Разумеется исправив включа описание параметров в стиле JavaDoc

← →
Игорь Шевченко © (2006-12-07 10:24) [9]

Названия методов непонятные. Слишком общие, на мой взгляд.

← →
codeCleaner (2006-12-07 10:25) [10]

Можно в таком случае фрагмент ПРАВИЛЬНО снабженного комментариями кода ?

← →
codeCleaner (2006-12-07 10:27) [11]

> Игорь Шевченко © (07.12.06 10:24) [9]

Каких, например?

← →
ИА (2006-12-07 10:31) [12]

/** * Method annotation: * 1. Get list of orders where property "reservationEndDate" less than or equal to parameter "pDate" * 2. For resources, linked to that orders, set state to "free" * 3. For selected orders set state to "off" * @pDate Date Date of orders to be released * @session Session Session to use in services */ public void freeOrdersResources(Date pDate, Session session)

больше комментариев для _этого_ метода не требуется

← →
ИА (2006-12-07 10:34) [13]

Тьфу, давно не брал я в руки джавы

* @param pDate Date of orders to be released * @param session Session to use in services

Такие комментарии, конечно, лучше, чем ничего.
Я обычно ограничиваюсь описанием работы класса/метода в его заголовке.

> codeCleaner (07.12.06 10:20) [6]

> встречал коды, в которых прогеры, видимо, жалели непостоянно
> занятую i и до/после использования ее как счетчик цикла
> применяли для чего-либо другого...

Значит у них это была переменная, а не какой-то "счётчик цикла". Или по указу правящей группировки это запрещено?
PS. Кстати в своём коде через полгода Вы всё-равно ничего не поймёте.

Зачем полгода. Мне уже сейчас не по глазам.

> А как же извечные сетования на то, что через полгода без
> комментов даже в своем коде разобраться трудов стоит?

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

> // if list of orders is empty then exit
> if ( orderList.isEOF() ) {
> orderList.close();
> return;
> }

В противном случае не занимайся ерундой. Комментировать код надо не "шоб було", а с умом - там, где алгоритм не ясен и может требовать пояснений для постороннего читателя.

← →
codeCleaner (2006-12-07 11:36) [18]

Ок, спасибо за советы!
Я и сам где-то на уровне подсознания знал правильный ответ на свой вопрос, а вы помогли мне переместить его в область сознания... :)

Удобочитаем ли следующий код? Найти похожие ветки