Соблюдайте правильные отступы. Старайтесь разделять переменные с логическими операциями пробелами. Инденты лучше ставить либо четырьмя пробелами, либо знаками табуляции.
Имена переменных и функций лучше писать со строчной буквы латинского алфавита, кроме того — они должны и иметь смысл в своем названии. Не используйте символов транслита (написание русских слов латинскими символами).
Отдельные слова и предлоги в названиях переменных и функций разделяйте знаком подчеркивания, после которого ставится строчная латинская буква.
После названия функции, при ее объявлении фигурная скобка ставится с новой строки. Однако, после условий ветвлений и циклов, фигурная скобка ставится на той же строке и отделена одним пробелом от закрывающей круглой скобки.
int any_function_name()
Пример нечитаемого кода
#include using namespace std; int kalkul9tor(int a,int b) < int k; if(a>0b; <1) k=a+b; else return k;> int main () < int a,b; cout>a; cout>b;cout> a; cout > b; cout
Источник: code-live.ru
Вот Почему Твой Код — Говно | Python PEP-8
Оформление кода
Данным топиком я хочу поднять вопрос о качестве кода, независимо от используемого языка программирования. В топике я приведу пару советов и методик, которых придерживаются у нас в компании. Я не буду утверждать, что они являются верными, ведь у каждого есть свой вкус и свои предпочтения. Но все равно, в каждом кругу разработчиков, работающих вместе, существуют какие либо правила оформления кода.
Так же, не мало важно увидеть в комментариях ваши подходы и «любимый стиль».
Большинство советов в топике — вырезки из книги Макконнелла «Совершенный код» (Steve McConnell — «Code Complete»).
Многочисленные статистические исследования показывают, что среднестатистический программист проводит гораздо больше времени за чтением кода, а не его написанием. Читать код сложнее, чем писать его. Особенно если речь идет о чужом программном коде. Но вы можете серьезно облегчить работу себе и коллегам, если ваш код будет качественным, понятным. “Качество кода” довольно обширный термин, включающий в себя достаточно много разных аспектов, среди которых проектирование интерфейсов классов и методов, реализация методов, правильное взаимодействие классов и методов друг с другом, конвенции по форматированию и оформлению кода, именованию классов, методов и переменных, принятые в конкретной корпоративной среде.
Правило Ноль: строго следуйте code style «гайдам», принятым в вашей корпоративной среде.
Качественные методы
Метод должен служить одной четко определенной цели
Эта цель должна быть полностью отражена в его имени: получить текущего пользователя — getСurrentUser(). Размытое, неоднозначное и откровенно плохое имя метода чаще всего является
главным свидетельством его неудачной реализации.
Примеры хороших имен методов:
Как новичку научиться писать красивый код
Customer::getFullName() – получить полное имя клиента UserMapper::createAndGetUser(userId) – исключение, в контексте User-маппера побочная роль метода (вернуть вновь созданный user-объект) достаточно очевидна.
MonthRevenue.calculate(), MonthRevenue.export() – неинформативные сами по себе имена методов оказываются полностью достаточными в контексте ООП вызовов этих методов «на себя» (другими словами, метод призван совершить действие над вызвавшим его объектом и его данными).
Примеры плохих имен методов:
computeMonthRevenueAndDoExport() – несколько несвязанных целей
processInput(), handleCalculation() – невыразительность, размытость цели
метода
- Следует использовать парные антонимы для методов, выполняющих парные (противоположные) действия: open/close, show/hide, add/remove, insert/delete.
- Метод должен быть отформатирован в строгом соответствии с принятыми конвенциями, «код стайлами» и так далее.
- Метод должен быть документирован (как сам интерфейс метода, так и комментарии к важным и сложным участкам).
- Метод не должен изменять глобальные переменные.
- Метод не должен иметь слишком большое количество параметров (не более 7).
- Параметры следует упорядочивать по степени их важности либо порядку их использования внутри метода:
setMonthExchangeRate(month, exchangeRate)
getCustomerMonthRevenue(customerId, month)
monthRevenue = fixedValue * 0.6 / inputParam
Качественные переменные
Переменная должна полно описывать представляемую сущность
Суть этого совета проста – любая переменная должна иметь понятное название, по которому можно судить
о ее предназначении. Бессмысленных и неочевидных переменных стоит избегать. Имя переменной должно характеризировать проблему реального мира, а не ее решение на языке программирования. Проще всего словами проговорить описываемую переменной сущность и назвать переменную соответствующими словами.
Умеренная длина
Название переменной не должно быть слишком кратким, чтобы вводить в заблуждение людей, но в это же время оно не должно быть и слишком длинным, так как это некрасиво с точки зрения чтения кода. Длина должна быть достаточной, чтобы не нужно было ломать голову.
Спецификаторы
В именах переменных следует использовать спецификаторы Count и Index вместо Num. Это логично, так как они четко отражают назначение переменной (количество и номер), а вот Num выглядит достаточно двусмысленно и может в некоторых случаях ввести в заблуждение.
Индексы циклов
Это нормально, когда небольшой цикл из 1-3 строк имеет индекс под названием I,j или k. Но если тело цикла заметно больше, то лучше давать индексам осмысленные имена. И вам будет проще разобраться с таким кодом со временем (сразу же становится понятно, что делает цикл) и другим программистам, которые будут работать с вашим кодом, тоже станет легче.
Префиксы при перечислениях
При использовании перечислений имеет смысл ставить префикс. Например, в случае таких переменных STATUS_OPENED, STATUS_TO_CONFIRM, STATUS_CONFIRMED перечисление идет с префиксом STATUS_.
Константы
При именовании констант следует использовать не конкретные числа, а абстрактные сущности, о которых идет речь. Это боле понятно с точки зрения читабельности кода и является хорошим стилем программирования.
Конвенции
Следует использовать конвенции именования переменных, которые будут известны всей команде программистов. Код должен быть единообразным. Так каждому участнику проекта будет гораздо проще в нем разобраться. И это приведет к повышению эффективности работы. Конвенция должна быть очевидной и доступной всем.
И каждый разработчик должен придерживаться ее.
Меньше обобщенности
Называя переменную, старайтесь давать ей не слишком обобщенное имя. Идите в сторону конкретизации. Нужно четко представлять, для чего она предназначена. Даже если вам при обобщении это понятно, далеко не факт, что это будет очевидно для других разработчиков в вашей команде.
Примеры хороших имен переменных:
employeesCount, userMonthWorkDaysCount, yearTax, maxComputedSalary
Примеры плохих имен переменных:
x, $fb, f_ar_type_data, f_obj_result, inputData, returnValue, resultArray, obj1, obj2
- Хорошее правило — давать более короткие имена переменным с более узкой областью видимости, соответственно, более длинные и подробные имена — переменным с более глобальной (в рамках метода) областью видимости.
- Для переменных-счетчиков коротких циклов допускаются традиционные односимвольные имена — i, j, k, …. Если переменная будет использоваться вне цикла, ее имя должно быть более выразительным и понятным:
teamScoresCount = 0; teamScores = array(); while (teamScoresIterator.nextScore()) < teamScores[teamScoresCount++] = teamScoresIterator.getCurrentScore(); >foreach ($teamScores as $teamScoreIndex => $teamScoreValue) foreach ($aTeamScores as $iTeamScoreIndex => $iTeamScore) < // over 9000 lines of code >
- Располагать команды использующие одну и туже переменную как можно
ближе друг к другу. - Инициализировать переменные непосредственно перед их использованием
Так же не мало важным является одинаковое оформление блоков кода, разбиение длинных условий на несколько строк и использование отступов.
Согласитесь, читать такой код:
function()
Более приятно, чем
function()
Ссылка на книгу Code Complete.
Спасибо за внимание.
Источник: habr.com
Форматирование кода и комментарии к коду — руководство для начинающих
В этой статье мы рассмотрим лучшие практики форматирования и комментирования исходного кода в HTML, CSS, PHP и JavaScript. Вы узнаете для чего они нужны и как правильно их использовать.
Зачем документировать код?
Форматирование и комментирование исходного кода не влияет на его работоспособность. Компьютеры вполне способны правильно выполнять код и без них.
Устройствам все равно, выглядит ли исходный код красиво, до тех пор, пока он является корректным и не выдает ошибок. Но правильное форматирование и комментирование делает программные исходники более понятными для человека.
Поэтому были созданы правила комментирования кода, которые делают исходный код более понятным для сторонних разработчиков. Это помогает им устранять возникающие проблемы и упрощает обслуживание программного обеспечения.
Основные аспекты форматирования кода
Общие правила форматирования исходного кода включают в себя:
- Отступы.
- Разрывы строк.
- Конвенции об использовании заглавных букв и имен.
- Стиль и написание функций, переменных.
- Использование и стиль комментариев.
Как отформатировать код — основы
Далее мы приведем несколько советов по поводу того, как правильно форматировать код.
Отступы, разрывы строк и форматирование
Использование форматирования помогает идентифицировать части исходного кода, которые связаны друг с другом. Для этого используются отступы, разрывы строк и другие элементы.
HTML
В HTML-разметке отступы добавляются перед элементами, чтобы показать, что они вложены друг в друга.
Отступы добавляются с помощью табуляции или нескольких пробелов.
CSS
Вот несколько примеров правильного форматирования CSS-кода:
.search-submit
Обратите внимание, что между операторами, фигурными скобками и свойствами есть пробел, они расположены в алфавитном порядке и на отдельной строке. В том числе и закрывающая скобка.
Также, чтобы сделать CSS-код более понятным, можно использовать сокращение. Сравните эти два фрагмента кода:
.footer < margin-bottom: 10px; margin-left: 5px; margin-right: 5px; margin-top: 10px; >.footer
Благодаря использованию сокращенной формы свойства margin второе правило CSS намного короче.
При использовании медиазапросов убедитесь в том, что вложили в них правила и правильно указали отступ.
PHP
Аналогичные правила форматирования применяются и в PHP. Вот пример файла functions.php из темы оформления Twenty Nineteen:
function twentynineteen_widgets_init() < register_sidebar( array( ‘name’ =>__( ‘Footer’, ‘twentynineteen’ ), ‘id’ => ‘sidebar-1’, ‘description’ => __( ‘Add widgets here to appear in your footer.’, ‘twentynineteen’ ), ‘before_widget’ => », ‘after_widget’ => », ‘before_title’ => ‘
‘, ‘after_title’ => ‘
‘, ) ); > add_action( ‘widgets_init’, ‘twentynineteen_widgets_init’ );
Обратите внимание на отступы, переносы строк? Также обратите внимание, что все операторы => размещены на одном уровне. Это еще больше повышает читаемость кода.
JavaScript
Пример правильно отформатированного JavaScript- кода:
const HeadingColorUI = memo( function( < textColorValue, setTextColor, >) < return ( initialOpen= < false >colorSettings=< [ < value: textColorValue, onChange: setTextColor, label: __( ‘Text Color’ ), >, ] > /> ); > );
Конвенция об именовании
При именовании переменных, методов и функций важно, чтобы их имена отражали назначение каждого элемента кода. Вот несколько советов по поводу того, как это правильно реализовать.
Давайте осмысленные имена
Имена функций и методов должны объяснять, что делает этот фрагмент кода.
unregister_sidebar( ‘header-right’ );
Следуйте нормам конвенции
Языки программирования используют разные конвенции, и их нужно придерживаться.
В HTML и CSS все имена элементов, атрибутов, значений, селекторов, свойств, классов HTML и идентификаторов пишутся с маленькой буквы. Но в коде PHP и JavaScript встречаются следующие имена: camelCase , under_scores или with-hyphens.
Что правильно?
Сначала нужно изучить правила конвенции, которую использует программная платформа. Например, WordPress поощряет использование подчеркивания в PHP и camelCase в JavaScript. Поэтому, если вы работаете с платформой WordPress, рекомендуется придерживаться этих конвенций, тем более что многие существующие переменные и методы уже определены именно в этом формате.
Комментарии к коду
Но это только первый шаг. Также для повышения читаемости кода нужно добавить к нему комментарии.
Узнайте, как включить комментарии
Примеры добавления комментариев в различных языках программирования:
- HTML — . Если комментарий разбивается на несколько строк, используйте открывающие и закрывающие скобки и размещаете комментарии с отступом между ними.
- CSS — все, что находится между /* и */ является комментарием. Комментарии могут размещаться на нескольких строчках.
- PHP — поддерживает два типа комментариев: однострочные (отмечены // или #) и многострочные (создаются с помощью /* . */ из CSS).
- JavaScript — однострочные комментарии создаются с помощью //. Многострочные работают так же, как в CSS и PHP.
Хорошим примером комментирования кода является заголовок дочерней темы WordPress.
/* Theme Name: Twenty Seventeen Theme URI: https://wordpress.org/themes/twentyseventeen/ Author: the WordPress team Author URI: https://wordpress.org/ Description: Twenty Seventeen brings your site to life with header video and immersive featured images. With a focus on business sites, it features multiple sections on the front page as well as widgets, navigation and social menus, a logo, and more. Personalize its asymmetrical grid with a custom color scheme and showcase your multimedia content with post formats. Our default theme for 2017 works great in many languages, for any abilities, and on any device.
Version: 2.2 License: GNU General Public License v2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Text Domain: twentyseventeen Tags: one-column, two-columns, right-sidebar, flexible-header, accessibility-ready, custom-colors, custom-header, custom-menu, custom-logo, editor-style, featured-images, footer-widgets, post-formats, rtl-language-support, sticky-post, theme-options, threaded-comments, translation-ready This theme, like WordPress, is licensed under the GPL. Use it to make something cool, have fun, and share what you’ve learned with others. */
Используйте комментарии, чтобы уточнить разметку
Опишите, что делает конкретная функция или блок кода, к какому элементу относится фрагмент CSS и т. д. Например:
//* Добавляем новый размер изображений add_image_size( ‘blog’, 700, 300, TRUE );
Многие разработчики также используют комментарии для создания перечня CSS-стилей.
/*————————————————————— >>> TABLE OF CONTENTS: —————————————————————- 1.0 Normalize 2.0 Accessibility 3.0 Alignments 4.0 Clearings 5.0 Typography 6.0 Forms 7.0 Formatting 8.0 Lists 9.0 Tables 10.0 Links 11.0 Featured Image Hover 12.0 Navigation 13.0 Layout 13.1 Header 13.2 Front Page 13.3 Regular Content 13.4 Posts 13.5 Pages 13.6 Footer 14.0 Comments 15.0 Widgets 16.0 Media 16.1 Galleries 17.0 Customizer 18.0 SVGs Fallbacks 19.0 Media Queries 20.0 Print —————————————————————*/
Инструменты форматирования кода
Чтобы упростить форматирование кода, можно воспользоваться инструментами автоматизации:
Форматирование кода онлайн
Вот несколько онлайн-сервисов для автоматического форматирования кода:
- HTML Formatter .
- PHP Formatter .
- CSS Formatter and Beautifier .
- JavaScript Beautifier .
Плагины для редактирования кода
Также есть плагины, которые могут автоматически делать подобные вещи.
- Atom Beautify .
- HTML-CSS-JS Prettify for Sublime Text .
- io (работает с Atom, Espresso, Sublime Text, WebStorm и другими).
Руководства по стилю
- Google Style Guides .
- Mozilla Coding Style Guide .
Форматирование кода в двух словах
Форматирование кода и комментарии облегчают понимание кода и поддержку. Из этого руководства вы узнали основные способы их реализации для улучшения рабочего процесса.
Вадим Дворников автор-переводчик статьи « Code Formatting and Code Comments – A Beginner’s Guide to Do It Right »
Пожалуйста, опубликуйте свои комментарии по текущей теме статьи. Мы очень благодарим вас за ваши комментарии, лайки, дизлайки, отклики, подписки!
Источник: www.internet-technologies.ru