You are here: Home » Учебник » Стиль программирования и документирование

Стиль программирования и документирование

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

Стиль программирования имеет отношение к внешнему виду программы. Программа может быть удачно скомпилирована и запущена даже если она написана в одну строку, но запись её всю на одну строку будет плохим стилем программирования, поскольку её трудно будет прочесть. Документирование – это совокупность пояснительных замечаний и комментариев, относящихся к программе. Стиль программирования и документирование также важны как и написание кода. Хороший стиль программирования и надлежащая документация уменьшают шанс ошибок и делают программу лёгкой для чтения. В этом разделе приведены несколько рекомендаций.

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. Стили блоков

Блок – это группа инструкций, окружённых фигурными скобками. Имеется два популярных стиля, стиль «на следующей строке» и стиль «на конце строки», они показаны ниже.

Стиль «на следующей строке»:

Стиль «на конце строки»:

Стиль «на следующей строке» выравнивает фигурные скобки по вертикали и упрощает чтение программ, тогда как стиль «на конце строки» сохраняет пространство и может помочь избежать некоторых неуловимых ошибок программирования. Оба являются приемлемыми стилями блоков. Выбор зависит от личных или организационных предпочтений. Вы должны в одной программе использовать одинаковый стиль блока, смешивать стили не рекомендуется.

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

wp-puzzle.com logo