Ключевой момент: хороший стиль программирования и надлежащее документирование делают программу простой для чтения и помогают программистам предотвращать ошибки.
Стиль программирования имеет отношение к внешнему виду программы. Программа может быть удачно скомпилирована и запущена даже если она написана в одну строку, но запись её всю на одну строку будет плохим стилем программирования, поскольку её трудно будет прочесть. Документирование – это совокупность пояснительных замечаний и комментариев, относящихся к программе. Стиль программирования и документирование также важны как и написание кода. Хороший стиль программирования и надлежащая документация уменьшают шанс ошибок и делают программу лёгкой для чтения. В этом разделе приведены несколько рекомендаций.
1. Соответствующие комментарии и стиль комментариев
Включайте краткое описание в начало программы, которое объясняет, что программа делает, её ключевые функции и уникальные техники, которые она использует. В длинных программах вам также следует включать комментарии, которые представляют каждый важный шаг и объясняют всё, что трудно прочесть. Важно сделать комментарии краткими, чтобы они не теснили программу и не затрудняли ее чтение.
В дополнении к строковым комментариям (начинаются с //) и блочным комментариям (начинаются с /*), Java поддерживает комментарии специального типа, называемыми javadoc комментариями. Комментарии javadoc начинаются с /** и заканчиваются на */. Они могут быть извлечены в HTML файл используя команду javadoc из JDK.
Используйте комментарии javadoc (/** … */) для комментирования целого класса или целого метода. Эти комментарии должны предшествовать заголовку класса или метода, чтобы они могли быть извлечены в файл javadoc HTML. Для комментирования шагов внутри метода используйте построчные комментарии (//).
2. Надлежащие отступы и интервалы
Совпадающий стиль отступов делает программы понятными и удобными для чтения, отладки и поддержки. Отступы используются для иллюстрации структурных связей между компонентами или инструкциями программы. Java может читать программу, даже если все операторы находятся на одной и той же длинной строке, но людям легче читать и поддерживать код, который правильно выровнен. Отметьте каждый подкомпонент или оператор по крайней мере на два пробела больше, чем конструкция, в которой он вложен.
Следует добавить единичный пробел с обоих сторон бинарных операторов, как показано на следующей инструкции:
Плохой стиль
System.out.println(3+4*4);
Хороший стиль
System.out.println(3 + 4 * 4);
3. Стили блоков
Блок – это группа инструкций, окружённых фигурными скобками. Имеется два популярных стиля, стиль «на следующей строке» и стиль «на конце строки», они показаны ниже.
Стиль «на следующей строке»:
Стиль «на конце строки»:
Стиль «на следующей строке» выравнивает фигурные скобки по вертикали и упрощает чтение программ, тогда как стиль «на конце строки» сохраняет пространство и может помочь избежать некоторых неуловимых ошибок программирования. Оба являются приемлемыми стилями блоков. Выбор зависит от личных или организационных предпочтений. Вы должны в одной программе использовать одинаковый стиль блока, смешивать стили не рекомендуется.