Правила написания программ на java

В языке программирования Java есть большой набор не совсем официальных, но все же уважаемых среди разработчиков правил и соглашений касательно оформления кода. В случае с языком Java своего рода кодекс по оформлению программ называется Java Code Style. Предлагаем более подробно рассмотреть этот кодекс и понять, почему стоит использовать его в своей работе независимо от вашего опыта.

Что такое Java Code Style

Java Code Style — это набор правил и соглашений относительно форматирования и стиля написания кода на языке программирования Java. Он определяет, как должен выглядеть код, как именовать те или иные объекты, какие комментарии следует добавлять, и так далее. Цель Java Code Style состоит в том, чтобы сделать код более читабельным, понятным и поддерживаемым.

Каждая компания или команда разработчиков может создавать собственные своды правил на базе Java Code Style. Так, Oracle определяет собственный стиль написания кода под названием «Oracle Code Conventions for the Java Programming Language». Есть другие стандарты, такие как «Google Java Style Guide» и «Sun Code Conventions». Каждый из них имеет собственные особенности и подходы к разработке, но все они стремятся к общей цели — повышению качества и читабельности кода.

Программирование на Java для начинающих: #3 (Методы)

Зачем нужен Java Code Style

• До 80% затрат при разработке ПО приходится не на создание, а на поддержку и дальнейшее развитие кода. Если с чего читабельностью большие проблемы, расходы будут серьезные.
• Над проектом, как правило, работает несколько разработчиков в составе команды, зачастую довольно большой. Ее состав может меняться, как и любой другой рабочий коллектив. Единый стиль написания кода упрощает ввод новых специалистов в работу над проектом.
• Внесение изменений в код — лишь малая часть работы. В основном проект читают, и чтобы этот процесс был быстрым и эффективным, оформление должно быть понятным и единым.
• Поддержка проектов занимает гораздо меньше времени и усилий, когда все файлы имеют согласованный стиль оформления. В особенности это актуально для больших IT-разработок.

В конечном итоге, исходный код — продукт, который должен быть грамотно оформлен и упакован. Именно этого и помогает достичь Java Code Style. Давайте рассмотрим этот кодекс более подробно, узнаем, как оформлять код Java, писать комментарии, называть переменные и другие объекты.

Правила оформления кода Java

Вы можете найти полный кодекс Java Code Style на официальном сайте Oracle на английском языке с подробными примерами оформления кода в тех или иных ситуациях. Мы же рассмотрим главные правила и принципы коротко и доступно, так, чтобы вы смогли сразу применить их в своей работе.

Отступы и пробелы

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

Программирование на Java с нуля #6. Пакеты Структура программы

Максимальная длина одной строки кода — 80 символов. Строки, размер которых превышает такое ограничение, зачастую обрабатываются некорректно в большинстве современных сред разработки. Для работы с документацией ограничение еще строже — не более 70 символов в одной строке кода.

Отдельная тема — переносы длинных строек. В случае, если выражение настолько длинное, что его нельзя уместить в одной строке и укоротить, можно воспользоваться переносом по правилам:

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

В случае, если попытки перенести выражение на новую строку ухудшают читабельность кода, сразу после переноса введите 8 пробелов (одна единица табуляции). Как правило, это решает проблему.

Используйте пробелы для разделения двух и более аргументов (сразу после запятой), а также всех бинарных операторов от своих операндов за исключением точки. При этом будьте внимательны — пробел не используется для разделения инкремента, декремента и прочих унарных операторов.

Пустые строки

Для большей читабельности текста программы рекомендуем использовать пустые строки там, где это уместно. Так, две пустые строки принято устанавливать между секциями и определениями классов/интерфейсов. Одна пустая строка обязательно прописывается в перечисленных местах:

• между переменными метода и его первым по счету оператором;
• между двумя методами, расположенными друг рядом с другом;
• перед однострочным и/или блочным комментарием (об этом ниже).

Также одну пустую строку принято ставить между логическими частями кода внутри одного метода.

Наименования переменных

Переменные в языке Java именуются со строчной буквы. Если название состоит из двух или более слов, каждое из них, за исключением первого, указывают с большой буквы. Подчеркивания и тире не используются. Рекомендуется назвать переменные существительными, в том числе составными.

• правильные наименования: mailService, backDoor, louderBark;
• неправильные наименования: MailService, back-door, Louderbark.

При необходимости в названии переменных можно использовать уточняющие прилагательные.

Наименования методов

Методы именуются одним либо несколькими словами слитно без использования подчеркиваний и тире. Если название метода составное, первое слово указывают со строчной буквы, остальные — уже с заглавной. Так как метод — это действие, для его наименования принято использовать глаголы:

• правильные примеры: print (), parseText (), isScroll ();
• неправильные примеры: Print (), Parse-Text (), isscroll ().

Так как в языке программирования Java широко используются такие виды методов, как «геттеры» и «сеттеры», правила их наименования также прописаны в кодексе. В случае с геттерами название метода начинается с префикса get. Исключение — метод, взаимодействующий с переменной типа boolean. В этом случае название геттера начинается с префикса is, тем самым отвечая на вопрос.

Названия методов-сеттеров формируются так же, но вместо префикса get пишется приставка set.

Наименования классов

Классы и интерфейсы в языке Java именуются с заглавной буквы. Если имя составное, то есть в его структуре содержится два или более слова, каждое из них также прописывается с заглавной буквы. Слова в названии классов и интерфейсов указываются слитно. Тире и подчеркивания недопустимы:

• правильно: GuideBook, LastName, FullSize, BlueNumber;
• неправильно: guide_Book, lastname, Full-Size, Bluenumber.

В названии классов в языке Java принято использовать существительные. Если есть необходимость, к ним можно добавить прилагательное, которое уточняет наименование. Например, ImmutableList.

Наименование интерфейса может содержать существительные или прилагательные в случае, если речь идет о каком-либо свойстве. Что касается классов тестов, для большей читабельности кода их названия должны включать слово test на последнем месте. Примеры: SpeedTest, CrushTest и другие.

Наименования констант

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

Скобки и операторы

Фигурная скобка в коде на языке программирования Java открываются на той же строке, в которой находится код перед ней. Тело условного оператора или цикла рекомендуется размещать внутри фигурных скобок даже в том случае, если код занимает всего одну строку. Это предотвратит ошибку в случае добавления второй строки без добавления фигурных скобок. Вы сэкономите себе время.

Аббревиатуры и сокращения

Использование сокращений при разработке кода нежелательно хотя бы по той причине, что другие разработчики, которые заглянут в ваш проект, не поймут, что именно вы имели ввиду. Может быть и такое, что коллеги не найдут методы и классы со стандартизированными названиями и создадут их самостоятельно. Очевидно, что это утяжелит код и даже может привести к серьезным ошибкам.

Как не стоит сокращать: int lstId вместо int lastId, class CurPage вместо class CurrentPage и так далее.

Что касается аббревиатур, их применение зачастую неизбежно, но в ваших силах сделать их более читабельными. Для этого прописывайте аббревиатуры как слово только с одной заглавной буквой. Например, не HTMLPage, а HtmlPage, не class HTTPRequest, а class HttpRequest. Это смотрится лучше.

Комментирование кода

В ходе разработки программы на языке Java возможно использование двух видов комментариев — реализации и документации. К первым относятся комментарии, которые также применяются в C++. Они обозначаются следующим образом — /*…*/ и //. Документирующие, в свою очередь, есть лишь в Java. Для их обозначения используются символы /**…*/.

Особенность таких комментариев в том, что их можно извлекать из кода и отправлять в HTML-файл при помощи инструмента JavaDoc.

Комментирование можно использовать в отношении как отдельных строк, так и блоков, и даже в рамках целых алгоритмов, занимающих десятки и даже сотни строчек. Документирующие нужны в случае, когда стоит задача описать спецификацию программы (в том числе пользовательский интерфейс) вне зависимости от ее реализации. Такие комментарии пишутся в том числе для тех разработчиков, которые будут пользоваться софтом, не имея доступа к его исходному коду.

Java-разработчикам доступно четыре вида комментариев. Давайте рассмотрим их подробнее.

Блочные

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

Для визуального отделения блочного комментария от остального кода перед ним нужно оставлять пустую строку. Текст пояснения укладывается между открывающим тегом /* и закрывающим */. Каждая строка начинается символом *. Интересно, что при таком оформлении на комментарий не распространяется опция автоформатирования.

Однострочные

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

Прицепные

Если комментарий очень короткий, буквально в 2−3 слова, можно расположить его прямо на строке с описываемым кодом. Чтобы пояснение не сливалось с текстом программы, нужно сдвинуть его вправо. Количество пробелов не регламентировано, главное, чтобы был контраст на фоне кода. В случае использования нескольких прицепных пояснений их начала должны быть на одном уровне.

До конца строки

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

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

Правила объявления

Для удобочитаемости кода рекомендуется использовать одно объявление на строку. Это не только выглядит более читабельно в сравнении с нагромождением переменных или констант, но еще и упрощает дальнейшее комментирование программы. Чего точно нельзя делать, так это объявлять переменные и функции в одной строке, как и размещать таким образом переменные разных типов.

Вы сделаете код более понятным, если будете проставлять между типом и идентификатором не один пробел, а четыре. Необязательно нажимать Space четыре раза — достаточно нажать Tab.

Размещение

Объявления переменных размещаются только в самом начале блоков, то есть участков кода между фигурными скобками < >. Пожалуй, единственным допустимым исключением из этого правила будет объявление индексов в цикле for. В этом случае они указываются непосредственно в операторе.

Инициализация

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

Инструменты для оформления кода в IDE

Чтобы сэкономить время на ручном оформлении кода, подключите правила в среде разработки, которой пользуетесь в своей работе. Тот же Google Java Style Guide, упомянутый в начале статьи, можно скачать на GitHub и подключить в IDE как модуль. После установки остается дело техники — включить автоформатирование кода и наблюдать за тем, как оформление само приходит в норму.

Несмотря на возможность автоматического соблюдения правил и соглашений Java Code Style, все же стоит запомнить их и писать код изначально в соответствии с рекомендациями разработчиков.

Даже если вы начинающий разработчик и только учитесь, рекомендуем сразу привыкать к единым стандартам оформления кода. Поверьте, это лучше, чем долго переучиваться в дальнейшем, когда трудоустроитесь в более-менее серьезную команду. Более опытным разработчикам рекомендуем ознакомиться с полной версией Java Code Style в оригинале, доступной на сайте компании Oracle.

Источник: synergy.ru

Правила написания кода: сила правильных именований, хорошие и плохие комментарии

Как часто вам приходилось разбираться в чужом коде? Когда вместо пары часов ты тратишь дни, чтобы просто разобраться в логике происходящего. Самое забавное, что для человека, писавшего данный код, тут всё ясно и весьма прозрачно.

И это не мудрено: ведь совершенный или идеальный код — это весьма размытое понятие, ибо у каждого разработчика своё видение на мир и на код, соответственно, тоже. Не раз сталкивался с ситуацией, когда я и мой коллега смотрели на один и тот же код имели разное мнение насчет его корректности и чистоты.

Знакомое чувство, не правда ли? Тем не менее, есть некоторые моменты, проверенные временем, которых стоило бы придерживаться, что в итоге сыграет нам на руку, ведь если вы будете оставлять свой код в таком состоянии, в каком хотели бы сами хотели его получить, мир стал бы немножечко счастливей и чище.

В своей прошлой статье о правилах написания кода (а точнее, небольшом руководстве), мы немного пощупали рекомендации по написанию системы в целом и таких ее элементах как объекты, их интерфейсы, классы, методы и переменные. Там же я вскользь упоминал про правильные именования тех или иных элементов. Сегодня мне хотелось бы поговорить именно об этом, ведь правильные названия облегчают читаемость кода в разы. Закрывать же тему правильного кода будем с помощью размышлений и небольших примеров комментариев в коде — хорошо это или всё же не очень. Итак, давайте приступим.

Правильные именования

Правильные названия улучшают читабельность кода, соответственно экономя время на ознакомление, ведь куда проще использовать метод, когда название примерно описывает его функционал. Так как в коде все состоит из названий (переменные, методы, классы, объекты файлы и т. д.), этот пункт становится очень важным при создании правильного, чистого кода. Исходя из вышесказанного, имя должно передавать смысл, почему, например, переменная существует, что она делает и как используется. Ещё не раз отмечу, что лучшим комментарием для описания переменной служит ее правильное имя.

Именование интерфейсов

Интерфейсы, как правило, используют имена, начинающиеся с большой буквы и написаны в верблюжьем стиле (CamelCase). Раньше при написании интерфейса хорошей практикой считалось добавить префикс I для обозначения его как интерфейса (например, IUserService), но это выглядит весьма уродливо и отвлекает. В таких случая лучше писать без него (UserService), а к реализации его добавить -Impl (UserServiceImpl). Ну или на крайний случай, к его реализации добавить префикс С (СUserService).

Названия классов

Так же, как и у интерфейсов, имена пишутся с большой буквы и используют верблюжий стиль (CamelCase). Какой бы ни творился апокалипсис, как бы нb горели сроки, но никогда, запомните — никогда имя класса не должно быть глаголом! Имена классов и объектов должны быть существительными и их комбинациями (UserController, UserDetails, UserAccount, и так далее). Не следует снабжать имя каждого класса аббревиатурой данного приложения, так как это лишь добавит излишнюю сложность (например, у нас приложение User Data Migration, и мы к каждому классу добавим UDM — UDMUserDeatils, UDMUserAccount, UDMUserController).

Имена методов

Обычно названия методов начинаются с маленькой буквы, но и они юзают верблюжий стиль (СamelCase). Выше мы говорили про то, что имена классов никогда не должны быть глаголами. Тут же ситуация диаметрально противоположная: наименования методов как раз-таки должны быть глаголами или их сочетаниями с глаголами: findUserById, findAllUsers, createUser и так далее.

При создании метода (как впрочем, и переменных и классов), чтобы не запутаться, используйте один подход в именовании. Например, для поиска пользователя метод можно написать как getUserById или findUserById. И ещё: не используйте в названиях методов юмор, ибо шуточку могут и не понять, как и то, что делает этот метод.

Названия переменных

• begin/end
• first/last
• locked/unlocked
• min/max
• next/previous
• old/new
• opened/closed
• visible/invisible
• source/target
• source/destination
• up/down

Короткие имена переменных

Когда у нас есть переменные вида x или n или что-то вроде этого, мы сходу и не увидим намерения человека, писавшего код. Неочевидно, что делает метод n: он требует более вдумчивого осмысления (а это время время, время).

Например, у нас есть поле — id ответственного пользователя, и вместо какого-нибудь имени типа — x или просто id, мы назовем эту переменную responsibleUserId, что сходу нам повышает читаемость и осмысленность. Тем не менее, короткие имена вида n имеют место быть в качестве локальных перемен небольших методов, где блок кода с этой переменой — всего лишь пара строк кода, и имя метода прекрасно описывает, что там происходит. Разработчик, увидев такую переменную, понимает её второстепенность и весьма ограниченную область видимости. По итогу есть некая зависимость от длины имени переменных: чем длиннее оно, тем более глобальная переменная и наоборот. Как пример, метод для поиска последнего сохраненного пользователя по дате:

public User findLastUser() < return findAllUsers().stream() .sorted((x, y) ->-x.getCreatedDate().compareTo(y.getCreatedDate())) .findFirst() .orElseThrow(() -> new ResourceNotFoundException(«Any user doesn’t exist «)); >
Тут мы используем короткие именования x и y для задания сортировки стрима, и забываем про них.

Оптимальная длина

Продолжим тему длины имён.

Оптимальная длина имени — где-то между длиной имен maximumNumberOfUsersInTheCurrentGroup и n. То есть, слишком короткие страдают от недостатка смысла, а слишком длинные растягивают программу, не добавляя читабельности, и их просто лень каждый раз писать. Не учитывая вышеописанного случая, для переменных с коротким именем вида n нужно придерживаться длины примерно 8 -16 символов. Это не строгое правило: скорее как ориентир.

Малые различия

Не могу пройти мимо и малозаметных различий в именах, ведь это тоже плохая практика, так как можно просто напутать или потратить много лишнего времени на то, чтобы заметить незначительные различия в именах. Например, различие между InvalidDataAccessApiUsageException и InvalidDataAccessResourceUsageException беглым взглядом сложно обнаружить. Также часто дезинформация может возникнуть при использовании маленьких L и O, ведь их можно легко перепутать с 1 и 0: в некоторых шрифтах различие более очевидное, в некоторых — менее.

Смысловая часть

Нужно вкладывать смысловую часть в названия, но не переигрывать с синонимами, так как, к примеру, у UserData и UserInfo фактически один и тот же смысл, и придется немного поковыряться в коде, чтобы понять, какой конкретно объект нам нужен. Избегайте неинформативных слов, к примеру, firstNameString: к чему нам слово string? Разве может быть имя объектом типа даты? Конечно, нет: поэтому просто — firstName.

Ещё в качестве примера хотелось бы отметить boolean переменные, например, — flagDelete. Слово flag не несёт никакой смысловой нагрузки. Более разумным было назвать — isDelete.

Дезинформация

Также хотелось бы сказать пару слов о неправильных именованиях. Допустим, у нас есть именование userActivityList, и при этом названный так объект имеет не тип List, а какой-нибудь другой контейнер или кастомный объект для хранения. Это может ввести рядового программиста в ступор: уж лучше назвать как-то вроде userActivityGroup или userActivities.

Поиск

Одним из недостатков коротких и простых имен является то, что их сложно искать в большом объёме кода, ведь что будет проще найти: переменную с именем name или NAME_FOR_DEFAULT_USER? Конечно же, второй вариант. Нужно избегать в названиях часто встречаемых слов (букв), так это будет лишь увеличивать количество найденных файлов при поиске, что не есть гуд.

Хотелось бы напомнить, что за чтением кода программисты проводят больше времени, нежели за его написанием, так что с головой подходите к наименованию элементов вашего приложения. Но что если удачно назвать не получилось? Если название метода плохо описывает его функционал? Тут и выходит на сцену, наш следующий пункт — комментарии

• юридические комментарии — комментарии, оставляемые в начале каждого файла с исходным кодом, по юридическим соображениям, как например:

* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
/* * Объединяет пользователя из бд и пришедшего для обновления * Когда в requestUser поле пустое, оно заполняется старыми данными из foundUser */ private User mergeUser(User requestUser, User foundUser)

Stream.of(IOUtils.resourceToString(«/fill-scripts/» + x, StandardCharsets.UTF_8) .trim() .split(«;»)) .forEach(jdbcTemplate::update); // Вызов trim() очень важен, убирает возможные пробелы в конце скрипта // чтобы при считке и разбивке на отдельные запросы не было пустых

Плохие сценарии комментариев

бормочущий комментарий — комментарии, которые обычно пишут на скорую руку, смысл которых понятен только разработчику, писавшего их, так как только он видит ту ситуацию с теми нюансами, на которые он и ссылается. Рассмотрим данный пример:

public void configureSomeSystem() < try< String configPath = filesLocation.concat(«/»).concat(CONFIGURATION_FILE); FileInputStream stream = new FileInputStream(configPath); >catch (FileNotFoundException e) < //В случае отсутствия конфигурационного файла, загружается конфигурация по умолчанию >>
public class JdbcConnection< public class JdbcConnection< /** * Журнальный компонент, связанный с текущим классом */ private Logger log = Logger.getLogger(JdbcConnection.class.getName()); /** * Создаёт и возвращает connection с помощью входящих параметров */ public static Connection buildConnection(String url, String login, String password, String driver) throws Exception

/** * Вспомогательный метод, закрывает соединение со сканером, если isNotUsing истинно */ private void scanClose(Scanner scan, boolean isNotUsing) throws Exception < if (!isNotUsing) < throw new Exception(«The scanner is still in use»); >scan.close(); >
/** * Записи ведутся с 09 января 2020; ********************************************************************** * 09.01.2020 : Обеспечение соединения с БД с помощью Jdbc Connection; * 15.01.2020 : Добавление интерфейсов уровня дао для работы с БД; * 23.01.2020 : Добавление интеграционных тестов для БД; * 28.01.2020 : Имплементация интерфейсов уровня дао; * 01.02.2020 : Разработка интерфейсов для сервисов, * согласно требованиям прописанным в user stories; * 16.02.2020 : Имплементация интерфейсов сервисов * (реализация бизнес логики связанной с работой БД); * 25.02.2020 : Добавление тестов для сервисов; * 08.03.2020 : Празднование восьмого марта(Миша опять в хлам); * 21.03.2020 : Рефакторинг сервис слоя; */
// public void someMethod(SomeObject obj) < // . // >
/* * Начать с массива, размер которого достаточен для хранения * всех байтов данных (плюс байты фильтра) с запасом, плюс 300 байт * для данных заголовка */ this.dataBytes = new byte[(this.size * (this.deep + 1) * 2)+300];

Комментарий должен объяснять код, а не сам нуждаться в объяснениях. А что тут? Что за «байты фильтра»? При чём здесь +1? Почему именно 300?
Если уж решили писать комменты, вот пара советов по их использованию:

1. Используйте стили, которые будет легко поддерживать: поддерживать слишком причудливые и экзотические стили надоедает и съедает немало времени.
2. Не используйте комментарии в конце строк, относящихся к одиночным строкам: получается большое нагромождение комментов, при этом трудно придумать выразительный комментарий для каждой строки.
3. Придумывая комментарий, постарайтесь ответить на вопрос: «почему», а не «как».
4. Избегайте сокращений. Как и говорил выше, нам не нужно объяснение для комментария: комментарий и есть объяснение.
5. Можно использовать комментарии для пометки единиц измерения и диапазона допустимых величин.
6. Располагайте комментарии близко к описываемому ими коду.

Как итог всё же хочется напомнить: лучшие комментарий — это отсутствие комментария, а вместо него — грамотное именование в приложении. Как правило, большинство времени мы будем уже работать уже с готовым кодом, с его поддержанием и расширением. Гораздо удобнее, когда данный код удобно читаем и понятен, ведь плохой код мешает, ставит те еще палки в колёса и спешка — его верный товарищ. И чем больше у нас плохого кода, тем больше падает производительность, поэтому нужно время от времени устраивать рефакторинг. Но если с самого начала стараться писать код, за который вас не захотят найти и убить следующие разработчики, то и рефакторить его нужно будет реже. Но всё же нужно будет, так как условия, требования к продукту постоянно меняются, дополняются навешивая дополнительные связи, и от этого не убежать. Напоследок оставлю пару интересных ссылок для ознакомления с данной темой тут, тут и тут Пожалуй, на этом у меня сегодня всё, спасибо всем кто дочитал))

Источник: javarush.com

Оформление кода Java Code Conventions

Привет, сегодня поговорим про оформление кода java, обещаю рассказать все что знаю. Для того чтобы лучше понимать что такое оформление кода java, java code conventions , настоятельно рекомендую прочитать все из категории Разработка программного обеспечения и информационных систем.

оформление кода java

При написании программы на любом языке следует придерживаться какого-нибудь соглашения об оформлении кода. Соглашение, или стандарт, описывает, где и как надо ставить переносы строк, какие отступы делать для блоков кода, и так далее.

Зачем нужны соглашения об оформлении кода?

Если поначалу кажется, что оформление кода по стандарту — не так уж важно, то скажу следующее: около 80% времени работы над программой составляет поддержка. То есть, 80% уходит на поиск ошибок, на мелкие исправления и добавления новых функций. Другими словами, 80% времени приходится копаться в существующем коде.

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

Если же ваша «команда» состоит лишь из одного человека, то даже в этом случае необходимо придерживаться стандартов, ведь по прошествии времени самому придется возвращаться к старому коду, пытаясь вспомнить, как он работает. Сравните два отрывка одного и того же кода, оформленного по-разному. Один из них оформлен абы-как, а другой (угадайте, какой :)) — с использованием соглашения об оформлении кода «Java Coding Conventions». Какой из них проще понять?

public String toString() < int len = this.end — 0; char[] ss = new char[len]; for (int i = 0; i < len; i++) < ss[i] = this.cc[this.cci[i]]; >return String.valueOf(ss); >
public String toString() < int len=this.end; char[] ss=new char[len]; for(int i=0;i

Общепринятые соглашения об оформлении кода

Почти в каждой крупной организации или группе разработчиков есть свой стандарт оформления кода.

Один из стандартов, предложенный Sun для программирования на Java — «Java Code Conventions», следуя которому, получается весьма компактный, но в то же время прекрасно читаемый код. Java Code Conventions во многом применимы и для других языков, например, PHP. В программном коде для отступов Java Code Conventions разрешает использовать как пробелы, так и символы табуляции. Однако, практика показывает, что отступы пробелами более «надежны» в смысле переносимости кода. Например, код, отформатированный только пробелами, можно переносить из одного проекта в другой без потери форматирования, даже если в настройках разных проектов размер символа табуляции задан разный.

Во многих средах разработки по умолчанию сконфигурирован размер символа табуляции, равный четырем пробелам. Это, я убежден, в корне ошибочно. Исторически, символ табуляции занимает 8 пробелов от начала строки. Когда редактор вместо 4 пробелов ставит в файле символ табуляции, то открыв этот же файл любым другим редактором, отображающим «стандартные» 8 символов на табуляцию, получим свалку неформатированного кода. Это аукнется, когда изменения в программу придется вносить не любимым редактором в любимой тонко настроенной IDE, а каким-нибудь Far или обычным блокнотом, в полевых условиях.

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

int m_iCount; LPCTSTR m_lpszName;

Польза венгерской нотации — под вопросом, поскольку типы переменных могут часто меняться, особенно при активной разработке, да и вводить каждый раз конструкции вроде «m_lpszName» вместо «name» — удовольствие сомнительное.

Командная работа

В случае командной работы над проектом, какие бы ни были выбраны соглашения об отступах, переносах строки и прочих нюансах оформления кода, их по возможности следует хранить в свойствах проекта, чтобы при использовании системы управления версиями (SVN, GIT) эти настройки автоматически оказались бы у каждого разработчика. В Eclipse довольно тонкие настройки форматирования можно задать как на уровне Workspace, так и в самом проекте. В случае совместной работы, настройки следует делать именно в проекте.

Автоформатирование

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

Это позволяет не заморачиваться на форматировании, а дать команду IDE самой отформатировать код. Это можно сделать как для небольшого фрагмента, так и для всего файла. Автоформатирование средствами IDE — очень полезная возможность, которой следует пользоваться. Обычно форматирование исходника вызывается правым кликом по тексту программы в IDE, а дальше — выбираем пункт в выпадающем меню. Например, в NetBeans — Format. При командной работе настройки форматирования должны быть доступны через систему управления исходниками всем членам команды, поэтому и автоформатирование будет давать одинаковый результат. *** Соглашения по оформлению кода Java 1. Введение

1.1. Зачем нужны соглашения по оформлению кода

Соглашения по коду важны для программистов по ряду причин: • 80% расхода времени при использовании компонента программного обеспечения уходит на его обслуживание. • Редко программа поддерживается в течение всей своей жизни первым автором. • Соглашение по коду улучшает читаемость программного обеспечения, что позволяет инженерам понимать новый код более быстро и детально. • Если вы поставляете ваш код как продукт, нужно убедиться, что он так же хорошо сгруппирован и чист, как и любой другой продукт, который вы создаете.

1.2 . Об этом говорит сайт https://intellect.icu . Благодарности

2. Имена файлов

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

2.1. Расширения файлов

JavaSoft использует следующие расширения файлов: Тип файла |Расширение ———————— Исходный Java-код |.java Java-байткод |.class

2.2. Общепринятые имена файлов

Часто используемые имена для файлов включают в себя: Имя файла | Использование ———————— GNUmakefile | Предпочтительное имя для make-файлов. Мы используем gnumake для сборки нашего программного обеспечения. README | Предпочтительное имя файла, который суммирует содержимое определенного каталога.

3. Структура файла

Файл состоит из разделов, которые должны разделяться пустыми строками и необязательными комментариями, определяющими каждый раздел. Файлы длиннее 2000 строк громоздки и их следует избегать. В качестве примера правильного оформления Java программы, см. «Java Source File Example» на стр. 19.

3.1. Файлы исходники Java

Каждый исходный Java файл содержит один public класс или интерфейс. Когда private классы и интерфейсы связанны с public классом, вы можете поместить их в тот же исходный файл что и public класс. Public класс должен быть первым классом или интерфейсом в файле. Исходные Java файлы имеют следующую структуру: * Открывающие комментарии (см. «Открывающие комментарии» на стр.

4) * Сведения о пакете и импорте; например: import java.applet.Applet; import java.awt.*; import java.net.*; * Объявление классов и интерфейсов (см «Объявление классов и интерфейсов» на стр. 4) 3.1.1. Открывающие комментарии Все файлы исходники должны начинаться с комментария в стиле С, который дает список программиста(ов), дату, авторские права, а также краткое описание назначения программы. Например: /* * Имя класа * Информация о версии * * Примечание к копирайту */

3.1.2. Сведения о пакете и импорте

Первая строка не-комментарий в большинстве исходников Java это сведения о пакете, после чего идут сведения о импорте. Например: package java.awt; import java.awt.peer.CanvasPeer; 3.1.3 Объявление классов и интерфейсов Приведенная ниже таблица описывает объявление части класса или интерфейса в порядке их появления. См. «Пример файла исходника Java» на стр.

19 для примера с комментариями. |объявление части класса / интерфейса | примечания ———————————————————————————— 1 | Комментарии к документации класса/интерфейса (/**. */) | Смотрите “Комментарии к документации” на стр. 9 с информацией о том, что должно быть в этом комментарии.

2 | Операторы class или interface 3 | Комментарии о реализации класса/интерфейса (/*. */), если необходимо | Эти комментарии должны содержать расширенную информацию о классе/интерфейсе, которая не относится к комментариям документации класса/интерфейса 4 | Статические переменные класса | Сначала public переменные класса, затем protected, затем пакетные (без спецификатора доступа) и затем private. 5 | Не статические переменные | Сначала public, затем protected, затем пакетные (без спецификатора доступа) и затем private.

6 | Конструкторы 7 | Методы | Эти методы должны группироваться больше по функциональности чем по области видимости или доступности. Например, private метод класса может быть между двумя случайными public методами. Цель – сделать чтение и понимание кода проще. Отступы Один отступ должен содержать четыре пробела. Точный формат отступа (пробелы или знаки табуляции) не задан.

Табуляция должна содержать 8 пробелов (не 4).

4.1 Длина строки

• * начинайте новую строку после запятой
• * начинайте новую строку после оператора
• * переходите на новую строку на более высоком уровне в коде
• * когда часть выражения переносится на новую строку, начинайте ее на том же уровне, на котором находится начало выражения
• * если правила, указанные выше, приводят к тому, что код плохо читается или слишком сдвинут вправо, то просто делайте отступ в 8 пробелов.

Несколько примеров переноса строк для вызовов методов:

function(longExpression1, longExpression2, longExpression3,

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

longName1 = longName2 * (longName3 + longName4 — longName5)

+ 4 * longname6; // Лучше

longName1 = longName2 * (longName3 + longName4

— longName5) + 4 * longname6; // Хуже

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

// СОГЛАШЕНИЕ ПО ОТСТУПАМ

someMethod(int anArg, Object anotherArg, String yetAnotherArg,

// ДЕЛАЙТЕ ОТСТУП В 8 СИМВОЛОВ ДЛЯ ИЗБЕЖАНИЯ ГЛУБОКОЙ ВЛОЖЕННОСТИ

private static synchronized horkingLongMethodName(int anArg,

Object anotherArg, String yetAnotherArg,

Оформление строк для выражения if должно использовать 8-символьный отступ, т.к. использование стандартного (4-символьного) затрудняет просмотр тела выражения. Например:

// ТАК ОТСТУПЫ ДЕЛАТЬ НЕЛЬЗЯ

if ((condition1 condition2)

doSomethingAboutIt(); // ПОЗВОЛЯЕТ ЛЕГКО ПРОПУСТИТЬ ЭТУ СТРОКУ

// ЛУЧШЕ ОТСТУПЫ ДЕЛАТЬ ВОТ ТАК

if ((condition1 condition2)

if ((condition1 condition2) || (condition3 condition4)

Ниже приведены три приемлемых способа форматирования тернарных выражений:

alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta

5 Комментарии

У Java программ могут быть два вида комментариев: комментарии реализации и комментарии документации. Комментарии реализации, аналогичные комментариям в C++, ограничиваются /*. */ и //. Комментарии документации (известные как “doc comments”) встречаются только в Java и ограничиваются / **. */. На основе документирующих комментариев с помощью утилиты javadoc могут быть созданы файлы документации в формате HTML.

Комментарии реализации — средства для того, чтобы прокомментировать код или особенности реализации. Комментарии документации предназначены для описания характеристик кода не зависящих от реализации, чтобы в будущем могли быть прочитанными разработчиком, у которого не обязательно будет под рукой исходный код.

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

Пояснение нетривиальных или неочевидных проектных решений допускается, но следует избегать дублирование информации, которая присутствует в коде (и понятна из него). Избыточные комментарии быстро устаревают. Вообще, избегайте любых комментариев, которые, скорее всего, устареют при развитии кода.

Замечание: Частота комментариев иногда отражает низкое качество кода. Если Вы почувствуете, что нужно добавить еще комментариев, подумайте, вероятно нужно переписать такой код, что бы сделать его более понятным.

Комментарии не должны быть вложены в большие блоки, со звездочками или другими символами.

Комментарии никогда не должны включать служебные символы, такие как возврат каретки и backspace.

5.1 Оформления комментариев реализации

Программа может содержать такие стили комментариев реализации, как: «блочный», «однострочный» или «комментарий в конце строки»

5.1.1 Блочный комментарий

Блочные комментарии используются для описания файлов, методов, структур данных и алгоритмов. Блочный комментарий должен присутствовать в начале каждого файла и перед каждым методом. Также их можно использовать и в других местах: например, внутри методов. Блочный комментарий внутри функции или метода должен быть выровнен по уровню комментированного кода.

Для отделения от остального кода блочный комментарий должен предваряться пустой строкой. Каждая строка блочного комментария, кроме первой, должна начинаться с символа «звездочки» («*»).

* Это блочный комментарий

Блочный комментарий начинается с «/*». Оформление тела комментария не должно изменяться. Пример:

* Это блочный комментарий с весьма специфичным

* оформлением, в котором не используются отступы

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

См. «Документирующий комментарий» на стр. 9.

5.1.2 Однострочные комментарии

Короткий комментарий можно разместить на одной строке, выровненой по уровню следующего за ним кодом. Если комментарий не умещается на одной строке, его нужно записать как блочный комментарий(смотри раздел 5.1.1). Перед однострочным комментарием стоит оставить пустую строку. Вот пример кода с однострочным комментарием (см. также «Документирующие комментарии» на стр. 9):

5.1.3 Комментарии в конце строки (блочные)

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

Вот пример кода с блочным комментарием в конце строки (см. также «Документирующие комментарии» на стр. 9)

return TRUE; /* исключение */

return isprime(a); /* только для нечетной a */

5.1.4 Комментарии в конце строки (однострочные)

«//» — знак означающий начало однострочного комментария в плоть до конца строки. Он может занимать всю строку или только ее часть. Не стоит использовать однострочный комментарий для многострочного текста; однако, так можно закомментировать часть кода. Пример всех трех стилей:

// Делаем двойной перевот

return false; // Объясняю почему здесь.

// // Делаем тройной переворот.

5.2 Документирующие комментарии

Документирующие комментарии применяются при описании классов , интерфейсов, конструкторов, методов и полей. Каждый документирующий комментарий заключается в /**. */ и относится только к какому-то одному конкретному элементу API. Этот комментарий должен предшествовать элементу, для которого делается описание:

> else if (условие)

for (инициализация; условие; обновление)

for (инициализация; условие; обновление);

Источник: intellect.icu