Комментирование АПЕКС кода

Привет всем!

То там, то здесь вижу комментарии в чужом коде.

Есть ли какие-то устояшиеся нормы, шаблоны как правильно делать комментарий-"шапку",
может быть какие-то комменты об изменениях в коде,
коментарии о функционале кода.

У вас есть какие -то шаблоны, или "традиции" в построении, оформлении комментариев? Или обязательные для вашей компании правила о комментировании кода?

спасибо

Den Brown

Привет всем!

То там, то здесь вижу комментарии в чужом коде.

Есть ли какие-то устояшиеся нормы, шаблоны как правильно делать комментарий-"шапку",
может быть какие-то комменты об изменениях в коде,
коментарии о функционале кода.

У вас есть какие -то шаблоны, или "традиции" в построении, оформлении комментариев? Или обязательные для вашей компании правила о комментировании кода?

спасибо

Привет! Я придерживаюсь java-ских

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Artem Levchenko

Привет! Я придерживаюсь java-ских

[url]http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html[/url]

Art Vegas

Привет! Я придерживаюсь java-ских
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

спасибо за ссылку!

Den Brown

[quote="Art Vegas"]Привет! Я придерживаюсь java-ских

[url]http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html[/url][/quote]

спасибо за ссылку!

Внимательно прочитал статью по указанной ссылке.

Как я понял, там описываются правила написания Documentation comments (doc comments), из которых позже с помощью JDK tool Javadoc генерируется API Documentation.

Кто-будить пробовал использовать этот Javadoc в работе?

Кто-будить пробовал использовать этот Javadoc в работе с SFDC?

И снова о комментариях. Кроме doc comments, описывающих работу какого-то метода в целом, я расставляю по самому коду пояснительные комментарии, например, "сейчас мы парсим стринг", "сейчас мы апдатируем записи информацией из дата-объектов" и пр. Есть ли какие-то устоявшиеся правила, как оформлять такие технические, "по-ходу-дела" комментарии?

Спасибо

Den Brown

Внимательно прочитал статью по указанной ссылке.

Как я понял, там описываются правила написания Documentation comments (doc comments), из которых позже с помощью JDK tool Javadoc генерируется API Documentation.

Кто-будить пробовал использовать этот Javadoc в работе?

Кто-будить пробовал использовать этот Javadoc в работе с SFDC?

И снова о комментариях. Кроме doc comments, описывающих работу какого-то метода в целом, я расставляю по самому коду пояснительные комментарии, например, "сейчас мы парсим стринг", "сейчас мы апдатируем записи информацией из дата-объектов" и пр. Есть ли какие-то устоявшиеся правила, как оформлять такие технические, "по-ходу-дела" комментарии?

Спасибо

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

ставите ли вы в рабочий код и в каких случаях ставите, и как оформляете
SYSTEM.DEBUG();

я ставлю так:
public String line = ' **********************';
// чтобы видно было в логе, но нет сил видеть эти звездочки по всему коду
SYSTEM.DEBUG(line+var+line);

Также: как использовать
System.assertEquals( true, b);

как я вижу неравенство провоцирует
FATAL_ERROR|System.AssertException: Assertion Failed: Expected: true, Actual: false

получается, что System.assertEquals( ) можно использовать только для отладки кода, но не в рабочем?

Den Brown

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

ставите ли вы в [b]рабочий код[/b] и в каких случаях ставите, и как оформляете
SYSTEM.DEBUG();

я ставлю так:
public  String line = ' **********************';  
// чтобы видно было в логе, но нет сил видеть эти звездочки по всему коду
SYSTEM.DEBUG(line+var+line);

Также: как использовать 
System.assertEquals( true,   b);

как я вижу неравенство провоцирует 
FATAL_ERROR|System.AssertException: Assertion Failed: Expected: true, Actual: false

получается, что System.assertEquals( ) можно использовать только для отладки кода, но не в рабочем?

Я использую

SYSTEM.DEBUG('XXXXX - '+someVar); легко найти в логе, потом легко найти в исходниках, чтобы уделить перед отправкой заказчику. Не мозолит глаза.

System.assertEquals( true, b);

Используется только в тестах, собственно как и другие аналогичные assert методы.
В обычном коде их использовать нет смысла. Если хочешь что-то сравнить и вывести сообщение IF в помощь.

Dmitry Shnyrev

Я использую 

SYSTEM.DEBUG('XXXXX - '+someVar); легко найти в логе, потом легко найти в исходниках, чтобы уделить перед отправкой заказчику. Не мозолит глаза.

[quote]System.assertEquals( true, b);[/quote]
Используется только в тестах, собственно как и другие аналогичные assert методы.
В обычном коде их использовать нет смысла. Если хочешь что-то сравнить и вывести сообщение IF в помощь.