День сороковой. #CodeComplete
Командная работа

Важно:
1. По статистике код в среднем «переживает» до 10 поколений поддерживающих его программистов.
2. Программисты, поддерживающие код, проводят 50-60% своего времени, читая код.

Поэтому критически важно писать код, который будет понятен другим людям. Написание кода, понятного компилятору компьютера, это данность для любого программиста. Написание кода, который могут понять другие люди, это признак настоящего профессионала.

Помимо собственно грамотно написанного кода, его пониманию способствуют комментарии.

Виды комментариев:
1. Повторяющие код. Такие комментарии не нужны, их необходимо убрать.

// добавляем 1 к i
i = i + 1;

2. Объясняющие код.

// i обозначает номер клиента
i = i + 1;

Замените i на какое-нибудь значимое имя, например, customer, и уберите такие комментарии.
3. Отмечающие место в коде.

return null; // *** НЕ СДЕЛАНО!!! ***

Замените такой комментарий на стандартный блок TODO.
4. Комментарии исправлений. Переместите такие комментарии в систему контроля версий.

for i = 1 to maxElements-1 //исправлена ошибка №1234

5. Кратко объясняющие суть блока кода. Важно поддерживать актуальность таких комментариев!
6. Описывающие предназначение кода. Используйте комментарии, близкие к реальному миру, а не к техническим подробностям реализации, например:

// получаем информацию о работнике

вместо

// обновляем объект employeeRecord

7. Содержащие информацию, которая не может быть представлена в коде. Например, авторские права, Javadoc, ссылки на онлайн ресурсы и т.п.
8. Содержащие краткий обзор или вводную информацию для модуля или библиотеки.