1. Про керівництво "Стиль кодування на С #" в рамках Gray LLC

Даний документ написаний на основі неофіційного стандарту запропонованого
Mike Krueger. (The SharpDevelop C # Coding Style Guide by Mike Krueger).
Завдяки цим документом у Вас є можливість розробляти
"Читабельний" код і як наслідок надійний і легко переносимість. Основним
в ньому є правила форматування коду, написаного на мові C #, але
більшість прийомів можна застосувати і для інших мов
програмування.

Документ розроблявся для компанії Gray LLC.

 

2. Організація файлів

 

2.1 Вихідні файли на C #

Намагайтеся зберігати структуру класів / файлів невеликими розмірами,
до 2000 рядків коду. Розділяйте код на файли, це допоможе Вам створювати
більш чітку інфраструктуру програми. Поміщайте кожен клас у
окремий файл з однойменною назвою (збігалася з назвою класу)
і розширенням. cs.

 

2.2 Дерево файлових директорій

Створюйте директорію для кожного namespace.

Наприклад для: MyProject.TestSuite.TestTier ієрархія директорій буде
мати наступний вигляд: MyProject / TestSuite / TestTier.

Як видно з приклад крапка в рядку namespace замінюється на символ
слеша ("/") при написанні директорій.

 

3. Структуроване розташування тексту

 

3.1 Довжина рядка

Намагайтеся уникати (наскільки це можливо) рядків, довжиною більше
80-ти символів. Присутність лінійки в редакторі коду значно
полегшує цей контроль. Якщо рядок перевищує розмір 80-ти символів
використовуйте синтаксис перенесення рядка (див. 3.2)

 

3.2 Перенесення довгих рядків

У тому випадку, якщо рядок перевищує довжину 80 символів, то для її
переносу використовуються основні принципи описані нижче.

Рядок можна переносити в разі, якщо:

Приклад розбиття рядка при виклику аргументів методу:

		longMethodCall(expr1, expr2, expr3,
			expr4, expr5);

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

	var = a * b / (c - g + f) +
			4 * z; // PREFER

і другим (з форматуванням За переносимості висловом)

		var = a * b / (c - g +
	  f) + 4 * z; // AVOID

 

3.3 Прогалини

Ніхто, хто хоче досягти якісного рівня написання коду не повинен
використовувати прогалини для форматування відступів в коді. І робиться це
тому, що різні розробники використовують різну кількість для символів
табуляції. Один – розмір 2-х символів, інший 4-ри третьому 8-м. У
випадку, якщо ви будете використовувати стандартний табулятор для відступу,
то будь-який розробник може перенастроювати його під свій стандарт, що
значно полегшить модифікацію написаного коду в майбутньому.

Ось кілька аргументів на користь використання табулятора:

! НЕ Використовуйте пробіли замість символу табуляції!!

 

4. Comments

 

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

Як правило, використовується блоковий коментар для опису, а так само
стандартний «///» коментар для самодокументірованія.

Для стандартних блокових коментарів використовуються наступні стилі:

		/*
		* Line 1
		* Line 2
		* Line 3

* / Або такий стиль:

		/* blabla */

 

4.2 Коментар "до кінця рядка"

Для коментарів в один рядок використовується «С + +» подібний стиль:
«/ /» Цей стиль найбільш зручний при документуванні параметрів.
Переважно використовувати даний стиль замість / * коментар * / там,
де це можливо.

 

int i; / / мінлива для циклу

 

4.3 Коментарі для самодокументірованія

Теги для самодокументірованія, також можуть використовуватися
розробниками для опису. Але має враховуватися і той факт, що він
повинен узгоджуватися з вимогами до документування вихідного коду.

<c> <para>  <see>  
<code>  <param>  <seealso>  
<example>  <paramref>  <summary>  
<exception>  <permission>  <value>  
<include>  <remarks>    
<list> <returns>   

Даний розділ докладно описаний у документації Microsoft

 

5. Оголошення

 

5.1 Кількість оголошень на одній лінії

Загальноприйнятим стандартом в оголошеннях є один рядок на
екземпляр. Завдяки цьому з'являється зручність читання та написання
коментаря:

		int level; // indentation level
		int size; // size of table

не розміщуйте оголошення в один рядок!

int a, b; / / Неправильно!

5.2 Ініціалізація

Ініціалізує локальні змінні в тому ж місці де й розкажете.

Наприклад:

		string name = myObject.Name;

або

		int val = time.Hours;

 

5.3 Оголошення класів та інтерфейсів

У процесі розробки класів і інтерфейсів, дотримуйтесь наступних
правилами:

Між назвою методу і відкриває дужкою з перерахуванням
параметрів не повинна бути присутньою пробіл.

Відкриваюча фігурна дужка "{« повинна починатися на наступному рядку
відразу під назвою класу або його методу. Код, який слід під
відкриває фігурною дужкою «{«, повинен знаходиться на зміщенні одного
Tab символу вправо. Закриваюча фігурна дужка «}» повинна знаходиться на
рівні відкриває і охоплювати весь блок коду.

Наприклад:

	class MySample : MyClass, IMyInterface
	{
		int myint;

		public MySample(int myint)
		{
			this.myint = myint;
		}

		void Inc()
		{
			++myint;
		}	

		void EmptyMethod()
		{
		}
	}

 

6 Оператори

 

6.1 Звичайні оператори

Бажано, щоб в кожному рядку був присутній один оператор

 

6.2 Оператори повернення

Оператори повернення не повинні використовувати дужок.

 

6.3 If, if-else, if else-if else оператори

Код з використанням операторів if, if-else і if else-if else повинен
виглядати наступним чином:

У простому випадку:

 

	if (condition) 
	{
		DoSomething();
		...
	}

У більш ускладненому:

	if (condition) 
	{
		DoSomething();
		...
	}
	else 
	{
		DoSomethingOther();
		...
	}

І в самому складному:

	if (condition) 
	{
		DoSomething();
		...
	} 
	else if (condition) 
	{
		DoSomethingOther();
		...
	} 
	else 
	{
		DoSomethingOtherAgain();
		...
	}

 

6.4 For / Foreach оператори

Стиль оформлення коду для оператора For повинен мати наступний вигляд:

	for(int i = 0; i < 5; ++i) 
	{
		...
	}

Також допускається формат в один рядок:

	for(initialization; condition; update) ;

А оператор foreach повинен виглядати наступним чином:

	foreach(int i in IntList) 
	{
		...
	}

 

6.5 While / do-while оператори

Оператор While підлягає наступному форматування:

	while(condition) 
	{
		...
	}

Порожній оператор While може бути мати вигляд:

	while(condition);

Для Do-While застосуємо наступний формат:

	do 
	{
		...
	} while (condition);

6.6 Switch оператори

Оператор Switch повинен відповідати наступного формату:

	switch (condition) 
	{
		case A:
			...
			break;
		case B:
			...
			break;
		default:
			...
			break;
	}

 

6.7 Try-catch оператори

Формат написання операторів try – catch повинен мати наступний вигляд:

	try 
	{
		...
	} 
	catch (Exception) 
	{}

або

	try 
	{
		...
	} 
	catch (Exception e) 
	{
		...
	}

або

	try 
	{
		...
	} 
	catch (Exception e) 
	{
		...
	} 
	finally 
	{
		...
	}

 

7 Порожні рядки і прогалини у форматуванні коду

 

7.1 Порожні рядки

Порожні рядки допомагаю розбивати код додатку на логічні
сегменти.

Кількома рядками можуть відділятися:

Однією порожній рядком відокремлюються один від одного:

 

7.2 Прогалини

Один пробіл используеться в оголошенні методів після коми, але не
перед дужками:

	TestMethod(a, b, c); 

Приклад неправильного використання:

	TestMethod(a,b,c);

або

	TestMethod( a, b, c );

Так само одиночний пробіл може бути використаний для виділення операторів:

	a = b;  

неправильне використання:

	a=b;

Також прогалини використовуються і при форматуванні циклів:

	for (int i = 0; i < 10; ++i) ;

так не потрібно використовувати:

	for (int i=0; i<10; ++i)

або

	for(int i=0;i<10;++i)

 

7.3 «Табличне» форматування

При оголошенні та ініціалізації змінних бажано використовувати
«Табличне» форматування:

	string name	=	"Mr. Ed";
	int myValue	= 	5;
	Test aTest	= 	Test.TestYou;

 

8 Угода про іменуванні

 

8.1 Формати іменування

 

8.1.1 Pascal Casing

При цьому стилі, кожне логічне слово має починатися з великої
літери. (Наприклад: TestCounter)

 

8.1.2 Camel Casing

Ця угода встановлює правила написання за наступною схемою:
перший символ першого логічного слова з маленької літери, інші
логічні слова з великої, подібно Pascal Casing. (Наприклад:
testCounter)

 

8.1.3 Upper case

При цьому угоді в іменуванні використовуються тільки великі літери.
Цей стиль використовується тільки при іменуванні «коротких» констант,
наприклад PI або E. В інших випадках бажано використовувати Pascal
Casing.

Наприклад:

	public class Math
	{
		public const PI = ...
		public const E = ...
	}

 

8.1.4 Зведена таблиця використання іменувань

Type Case Notes 
Class / Struct Pascal Casing   
Interface Pascal Casing Starts with I 
Enum values Pascal Casing   
Enum type Pascal Casing   
Events Pascal Casing   
Exception class Pascal Casing End with Exception 
public Fields Pascal Casing   
Methods Pascal Casing   
Namespace Pascal Casing   
Property Pascal Casing   
Protected/private Fields Camel Casing   
Parameters Camel Casing   

 

8.2 Класи і члени класів.

На поточний момент украй не рекомендується використовувати угорську
нотацію за допомогою символу підкреслення. В угорській нотації
використовувалася суффіксная і постфіксній приставка для іменування
змінних.

У поточному документі Угорська нотація розглядатися не буде.

 

8.2.1 Іменування класів

Клас повинен іменуватися як іменник в однині або
множині;

Використовується Pascal Casing (см 8.1.1);

Не використовуйте ніяких префіксів при іменуванні класу.

 

8.2.2 Іменування інтерфейсів

При іменуванні інтерфейс повинен мати іменник в
однині або множині, яка максимально описує його
призначення. (Наприклад: IComponent or IEnumberable)

Використовується Pascal Casing (см 8.1.1);

Використовується в якості префікса заголовна буква "I", що є
першою літерою слова interface.

 

8.2.3 Іменування перерахувань

Використовується Pascal Casing (см 8.1.1) як для іменування enum так і
для його значень; Суфікси і префікси не використовуються;

Не використовуйте назв в однині для іменування enum;

Не використовуйте множини при іменуванні «полів» enum.

 

8.2.4 Константи і поля Read Only

Використовується Pascal Casing (см 8.1.1);

 

8.2.5 Параметри і нестатичні поля

Використовуйте «описові» назви для іменування полів, які
достатньо повно описують їх функціональні вимоги, а так їх же
тип. Використовується Camel Casing (см 8.1.2);

 

8.2.6 Іменування змінних

Використовується наступний префікс для вказівки типів змінних:

C# Type
. NET Framework type Префікс 
bool  System.Boolean  b
 
byte  System.Byte  by
 
sbyte  System.SByte  sby
 
char  System.Char  c
 
decimal  System.Decimal  dc
 
double  System.Double  d
 
float  System.Single  f
 
int  System.Int32  i
 
uint  System.UInt32  ui
 
long  System.Int64  l
 
ulong  System.UInt64  ul
 
object  System.Object  o
 
short  System.Int16  sh
 
ushort  System.UInt16  ush
 
string  System.String  s

Використовуйте змінні i, j, k, l, m, n для оформлення циклів;

Використовується Camel Casing (см 8.1.2);

 

8.2.7 Іменування змінних усередині методів

Для внутрішніх змінних методів крім тих 8.2.6 використовується
префікс "_", наприклад: _iNewRec;

Використовується Camel Casing (см 8.1.2);

 

8.2.8 Іменування методів

Називайте методи дієслівними формами єдиного чи множинного
числа; Використовується Pascal Casing (см 8.1.1);

 

8.2.9 Іменування властивостей

Називайте властивості іменниками єдиного чи множинного
числа;

Використовується Pascal Casing (см 8.1.1);

Називайте властивості таким же імеменем як і закрита мінлива,
яке використовує властивість якщо вона є.

 

8.2.10 Іменування подій

При іменуванні подій використовуйте суфікс EventHandler

Використовуйте два параметри іменовані "sender" і "e"

Використовується Pascal Casing (см 8.1.1);

Для іменування класів аргументів подій використовуйте суфікс
EventArgs

Узгодьте назви з дієслівною формою

 

Поради щодо написання коду

 

9.1 "Наявність"

Намагайтеся застосовувати максимум інкапсуляції для примірників об'єктів
які ви створюєте. Не ставте public там де це не потрібно. Використовуйте
максимальний рівень захисту. Тобто намагайтеся відкривати доступ від
мінімального (private) до максимального (public).

Використовуйте Властивості замість прямого відкриття public, для змінних
класу.

 

9.2 "Магічні числа"

Не використовуйте так званих «магічних чисел». Замість цього
оголошуйте константи і статичні змінні:

	public class MyMath
	{
		public const double PI = 3.14159...
	}

10 Приклади коду

 

10.1 Приклад розміщення фігурних дужок

	namespace ShowMeTheBracket 
	{
		public enum Test 
		{
			TestMe,
			TestYou
		}

		public class TestMeClass
		{
			Test test;

			public Test Test 
			{
				get 
				{
					return test;
				}
				set 
				{
					test = value;
				}
			}
			void DoSomething()
			{
				if(test == Test.TestMe) 
				{
					...
				} 
				else 
				{
					...
				}
			}
		}
	}

10.2 Приклад іменування змінних

замість:

	for(int i = 1; i < num; ++i) 
	{
		meetsCriteria[i] = true;
	}

	for(int i = 2; i < num / 2; ++i) 
	{
		int j = i + i;
		while (j <= num) 
		{
			meetsCriteria[j] = false ;
			j += i;
		}
	}

	for(int i = 0; i < num; ++i) 
	{
		if(meetsCriteria[i]) 
		{
			Console.WriteLine(i + " meets criteria");
		}
	}

намагайтеся використовувати більш «інтелектуальне» іменування:

for (int primeCandidate = 1; primeCandidate <num; + + primeCandidate) 
	{
		isPrime[primeCandidate] = true;
	}

	for (int factor = 2; factor < num / 2; ++factor) 
	{
		int factorableNumber = factor + factor;
		while (factorableNumber <= num) 
		{
			isPrime[factorableNumber] = false;
			factorableNumber += factor;
		}
	}

for (int primeCandidate = 0; primeCandidate <num; + + primeCandidate) 
	{
		if(isPrime[primeCandidate]) 
		{
			Console.WriteLine(primeCandidate + " is prime.");
		}
	}
 

 

Схожі статті:


Сподобалася стаття? Ви можете залишити відгук або підписатися на RSS , щоб автоматично отримувати інформацію про нові статтях.

Коментарів поки що немає.

Ваш отзыв

Поділ на параграфи відбувається автоматично, адреса електронної пошти ніколи не буде опублікований, допустимий HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

*