что такое code convention

C# Coding Conventions

Coding conventions serve the following purposes:

Naming conventions

There are several naming conventions to consider when writing C# code.

In the following examples, any of the guidance pertaining to elements marked public is also applicable when working with protected and protected internal elements, all of which are intended to be visible to external callers.

Pascal case

When naming public members of types, such as fields, properties, events, methods, and local functions, use pascal casing.

When writing positional records, use pascal casing for parameters as they’re the public properties of the record.

For more information on positional records, see Positional syntax for property definition.

Camel case

When editing C# code that follows these naming conventions in an IDE that supports statement completion, typing _ will show all of the object-scoped members.

When writing method parameters, use camel casing.

For more information on C# naming conventions, see C# Coding Style.

Additional naming conventions

Examples that don’t include using directives, use namespace qualifications. If you know that a namespace is imported by default in a project, you don’t have to fully qualify the names from that namespace. Qualified names can be broken after a dot (.) if they are too long for a single line, as shown in the following example.

You don’t have to change the names of objects that were created by using the Visual Studio designer tools to make them fit other guidelines.

Layout conventions

Good layout uses formatting to emphasize the structure of your code and to make the code easier to read. Microsoft examples and samples conform to the following conventions:

Use the default Code Editor settings (smart indenting, four-character indents, tabs saved as spaces). For more information, see Options, Text Editor, C#, Formatting.

Write only one statement per line.

Write only one declaration per line.

If continuation lines are not indented automatically, indent them one tab stop (four spaces).

Add at least one blank line between method definitions and property definitions.

Use parentheses to make clauses in an expression apparent, as shown in the following code.

Commenting conventions

Place the comment on a separate line, not at the end of a line of code.

Begin comment text with an uppercase letter.

End comment text with a period.

Insert one space between the comment delimiter (//) and the comment text, as shown in the following example.

Don’t create formatted blocks of asterisks around comments.

Ensure all public members have the necessary XML comments providing appropriate descriptions about their behavior.

Language guidelines

The following sections describe practices that the C# team follows to prepare code examples and samples.

String data type

Use string interpolation to concatenate short strings, as shown in the following code.

To append strings in loops, especially when you’re working with large amounts of text, use a StringBuilder object.

Implicitly typed local variables

Use implicit typing for local variables when the type of the variable is obvious from the right side of the assignment, or when the precise type is not important.

Don’t use var when the type is not apparent from the right side of the assignment. Don’t assume the type is clear from a method name. A variable type is considered clear if it’s a new operator or an explicit cast.

Don’t rely on the variable name to specify the type of the variable. It might not be correct. In the following example, the variable name inputInt is misleading. It’s a string.

Avoid the use of var in place of dynamic. Use dynamic when you want run-time type inference. For more information, see Using type dynamic (C# Programming Guide).

Use implicit typing to determine the type of the loop variable in for loops.

The following example uses implicit typing in a for statement.

Don’t use implicit typing to determine the type of the loop variable in foreach loops.

The following example uses explicit typing in a foreach statement.

Be careful not to accidentally change a type of an element of the iterable collection. For example, it is easy to switch from System.Linq.IQueryable to System.Collections.IEnumerable in a foreach statement, which changes the execution of a query.

Unsigned data types

Arrays

If you specify an array size, you have to initialize the elements one at a time.

Delegates

Use Func<> and Action<> instead of defining delegate types. In a class, define the delegate method.

Call the method using the signature defined by the Func<> or Action<> delegate.

If you create instances of a delegate type, use the concise syntax. In a class, define the delegate type and a method that has a matching signature.

Create an instance of the delegate type and call it. The following declaration shows the condensed syntax.

The following declaration uses the full syntax.

Use a try-catch statement for most exception handling.

Simplify your code by using the C# using statement. If you have a try-finally statement in which the only code in the finally block is a call to the Dispose method, use a using statement instead.

You can do the same thing with a using statement.

In C# 8 and later versions, use the new using syntax that doesn’t require braces:

&& and || operators

To avoid exceptions and increase performance by skipping unnecessary comparisons, use && instead of & and || instead of | when you perform comparisons, as shown in the following example.

If the divisor is 0, the second clause in the if statement would cause a run-time error. But the && operator short-circuits when the first expression is false. That is, it doesn’t evaluate the second expression. The & operator would evaluate both, resulting in a run-time error when divisor is 0.

new operator

Use one of the concise forms of object instantiation, as shown in the following declarations. The second example shows syntax that is available starting in C# 9.

The preceding declarations are equivalent to the following declaration.

Use object initializers to simplify object creation, as shown in the following example.

The following example sets the same properties as the preceding example but doesn’t use initializers.

Event handling

If you’re defining an event handler that you don’t need to remove later, use a lambda expression.

The lambda expression shortens the following traditional definition.

Static members

Call static members by using the class name: ClassName.StaticMember. This practice makes code more readable by making static access clear. Don’t qualify a static member defined in a base class with the name of a derived class. While that code compiles, the code readability is misleading, and the code may break in the future if you add a static member with the same name to the derived class.

LINQ queries

Use meaningful names for query variables. The following example uses seattleCustomers for customers who are located in Seattle.

Use aliases to make sure that property names of anonymous types are correctly capitalized, using Pascal casing.

Rename properties when the property names in the result would be ambiguous. For example, if your query returns a customer name and a distributor ID, instead of leaving them as Name and ID in the result, rename them to clarify that Name is the name of a customer, and ID is the ID of a distributor.

Use implicit typing in the declaration of query variables and range variables.

Align query clauses under the from clause, as shown in the previous examples.

Use where clauses before other query clauses to ensure that later query clauses operate on the reduced, filtered set of data.

Use multiple from clauses instead of a join clause to access inner collections. For example, a collection of Student objects might each contain a collection of test scores. When the following query is executed, it returns each score that is over 90, along with the last name of the student who received the score.

Источник

Java Code Style: как правильно оформлять код Java

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

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

Зачем нужен единый стиль кода

Java Code Style — это рекомендации и соглашения о стиле кода, собранные вместе. Например:

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

Причины, по которым разработчики пришли к таким соглашениям, логичны и просты:

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

Преподаватель Skillbox. Пишет про Java, учит Go. Помнит рассвет PHP и как «грабить корованы».

Форматирование на практике

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

Источник

Что такое code convention

Уважаемые посетители! Если вы обнаружили в каком-нибудь слове ошибку!
Выделите это слово и нажмите Ctrl+Enter одновременно!
Заранее спасибо за сотрудничество!

Контакты

Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.

Соглашения по оформлению кода Java (Java Code Conventions)

Данный перевод не претендует на пальму первенства или как наиболее точный перевод! Думаю таких переводов в сети довольного много, может многие из них переведены куда лучше этого =)

Этот перевод я делал для себя в целях ознакомления с данным документом, да и правилам оформления кода в целом. В этом переводе отчасти использовались материалы с этого перевода.

Для себя я старался его сделать максимально удобоваримым для понимания и использования в дальнейшем =) По этому если кто хочет его использовать где-то в других местах, то не забываем указывать ссылку на этот материал или сайт http://www.magnumblog.space;)

А вообще пользуйтесь на здоровье.

1.1 Зачем нужны условные обозначения кода

Соглашения по оформлению кода важны для программистов по ряду причин:

1.2 Выражение признательности

В этом документе содержатся стандарты по оформлению кода на языка Java, представленные в спецификации от Sun Microsystems. Основные вклады от Питера Кинга, Патрика Нотона, Майка ДеМони, Джонни Канервы, Кэти Уолрата и Скотта Хоммеля.

По вопросам, связанным с адаптацией, модификацией или распространением этого документа, пожалуйста, прочитайте наше уведомление об авторских правах по адресу http://java.sun.com/docs/codeconv/html/Copyright.doc.html.

Комментарии к этому документу должны быть отправлены в нашу форму обратной связи по адресу http://java.sun.com/docs/forms/sendusmail.html.

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

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

В программах написанных на Java используются следующие расширения файлов:

2.2 Общие имена файлов

Часто используемые имена файлов включают:

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

Файлы длиной более 2000 строк являются громоздкими и их следует избегать.

Пример форматирования файла с исходным кодом Java приведен в разделе «Пример файла с исходным кодом Java».

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

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

Файлы с исходным кодом Java имеют следующий порядок:

3.1.1 Начальный комментарий

Все файлы с исходным кодом должны начинаться с комментария в стиле языка C, в котором перечислены авторы программы, дата, сведения об авторских правах, а так же кратко описание того, что делает программа. Для примера:

3.1.2 Операторы Package и Import

Первая строка без комментария в файле с исходным кодом Java это оператор package. После нее следует оператор import. Для примера:

3.1.3 Объявления классов и интерфейсов

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

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

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

Избегайте строк длиннее 80 символов, так как они не обрабатываются многими терминалами и инструментами.

4.2 Перенос строки

Если выражение не помещается на одной строке, разбейте его в соответствии с этими общими принципами:

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

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

Отступы в строках с оператором if следует применить по правилу 8-ми пробелов, так как если использовать стандартные 4-ре пробела, то поиск тела оператора будет затруднителен. Например:

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

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

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

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

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

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

Комментарии не должны содержать специальных символов, таких как символ конца страницы или backspace.

5.1 Формат реализации комментариев

В программах могут использоватся 4 вида комментариев: блочные, однострочные, прицепные и комментарии до конца строки.

5.1.1 Блок комментариев

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

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

Если блочный комментарий начинается с «/*-«, это означает в данном блоке используется особое форматирование, которое нельзя потерять (Такой блок не будет переформатирован средствами автоформатирования). Например:

Примечание: Если вы не используете средства автоформатирования, вам не обязательно использовать «/*-» в коде, но можете сделать это на случай того, что кто-то другой может запустить средства автоформатирования на вашем коде.

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

Однострочные комментарии (короткие комментарии) можно писать в одной строке используя отступ на уровне соответствующего блока кода, который он описывает. Если комментарий не помещается в одну строку, следует использовать блочный комментарий (смотрите «Блок комментариев»). Однострочному комментарию должна предшествовать пустая строка. Вот пример однострочного комментария в Java-коде (смотрите «Комментарии для документации»):

5.1.3 Прицепные комментарии

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

Старайтесь избегать комментирования каждой строчки кода подобным образом.

Пример прицепных комментариев в Java коде (смотрите также «Комментарии для документирования»):

5.1.4 Комментарии в конце строки

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

5.2 Комментарии для документирования

Примечание: смотрите «Пример файла с исходным кодом Java» для примеров форматов комментариев, описанных здесь.

Для получения дополнительной информации смотрите «Как написать комментарии к документу для Javadoc«, который включает в себя информацию о тегах комментариев документа (@return, @param, @see):

Для получения большей информации о документирующих комментариях и Javadoc, посетите домашнюю страницу Javadoc:

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

Обратите внимание, что классы и интерфейсы не имеют отступов, в отличии от их членов. Первая строка документирующего комментария (/**) для классов и интерфейсов не имеет отступов; каждая последующая строка документирующего комментария имеет 1 пробел (для вертикального выравнивания звездочек). Члены класса, включая конструкторы, имеют 4 пробела для первой строки документирующего комментария и 5 для остальных.

Если необходимо предоставить информацию о классе, интерфейсе, переменной или методе, не принадлежащую к документации, используйте блочный (смотрите раздел 5.1.1) или однострочный (смотрите раздел 5.1.2) комментарий непосредственно после объявления. Например, детали о реализуемом классе должны идти в таком комментарии в блоке реализации, а не в документирующем комментарии.

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

6.1 Количество объявлений в строке

Рекомендуется использовать одно объявление на строку, так как это облегчает комментирование. Другими словами:

Ни в коем случае нельзя объявлять переменные и функции в одной строке. Например:

Не помещайте переменные разных типов (имеется в виду не тип самих переменных, а тип данных которые в них хранятся) в одну строку. Например:

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

6.2 Размещение

Размещайте объявления только в начале блоков (блоком является любой код, заключенный в фигурные скобки «<«» и «>«). Не ждите объявления переменных до их первого использования; Это может запутать неопытного программиста и затруднить переносимость кода в пределах области.

Единственным исключением из этого правила являются индексы циклов for, которые в Java могут быть объявлены в операторе for:

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

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

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

6.4 Объявления классов и интерфейсов

При написании Java классов и интерфейсов необходимо соблюдать следующие правила форматирования:

7.1 Простые операторы

Каждая строка должна содержать не более одного оператора. Например:

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

7.2 Составные операторы

7.3 Оператор return

Оператор return, возвращающий значение, не должен использовать скобки, если только их использование не сделает возвращаемое значение более понятным. Например:

7.4 Операторы if, if-else, if-else-if-else

Группа операторов (как и еденичное использование) if-else должна иметь следующий вид:

Примечание: операторы if всегда должны использоватся с фигурными скобками » «. Избегайте следующей формы:

7.5 Оператор цикла for

Оператор цикла for должен иметь следующий вид:

Пустой оператор цикла for (тот, в котором вся работа выполняется в инициализации, условии и итерации) должен иметь следующий вид:

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

7.6 Оператор цикла while

Оператор цикла while должен иметь следующий вид:

Пустой оператор цикла while должен иметь следующий вид:

7.7 Оператор цикла do-while

Оператор цикла do-while должен иметь следующий вид:

7.8 Оператор switch

Оператор switch должен иметь следующую форму:

Каждый раз, когда выбор проваливается (не включая оператор break), добавьте комментарий, где обычно находится оператор break. Это показано в предыдущем примере кода с комментарием /* провал */.

Каждый оператор switch должен включать выбор по умолчанию (default). Оператор break в выборе по умолчанию лишний, но он предотвращает возникновение ошибки, если позже еще ​​один выбор добавится.

7.9 Оператор try-catch

Оператор try-catch должн иметь следующий формат:

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

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

Две пустые строки всегда должны использоваться в следующих случаях:

Одна пустая строка всегда должна использоваться в следующих случаях:

8.2 Расстановка пробелов

Разделяющие пробелы должны ставиться при следующих обстоятельствах:

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

Правила, приведенные в данном разделе, являются основополагающими. Более конкретные правила приведены в таблице:

10.1 Обеспечение доступа к экземпляру и переменным класса

Одним из примеров уместного использования public полей может быть случай, когда класс описывает лишь структуру данных, без какого-либо поведения. Другими словами, если бы вы могли использовать struct вместо class (если бы Java поддерживал struct), тогда можно сделать переменные экземпляра класса public.

10.2 Обращение к переменным и методам класса

Избегайте использование объекта для доступа к статическим полям и методам класса. Вместо этого используйте имя класса. Например:

10.3 Константы

Численные константы (литералы) не должны кодироваться напрямую, за исключением -1, 0 и 1, которые могут использоваться в циклах для управления счетчиком.

10.4 Примеры присваивания значение переменным и операторам и т.д.

Избегайте присваивания значения некоторым переменным в одном выражении. Это усложняет чтение. Например:

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

лучше написать так:

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

дожно быть написано так:

10.5 Различные приёмы программирования

10.5.1 Круглые скобки

10.5.2 Возврат значения

Попробуйте сделать структуру вашей программы понятной. Например:

вместо этого следует записать так:

лучше записать так:

10.5.3 Выражения перед ‘?’ в условном операторе

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

10.5.4 Специальные комментарии

Используйте XXX в комментарии для того, чтобы показать, что этот код неправильный, но работает. Используйте FIXME для того, чтобы показать, что код неправильный и не работает.

11.1 Пример файла с исходным кодом Java

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

Версию для оффлайн чтения можно найти в моем репозитории Github

Источник