Правила за проектиране на код

Съдържание

Тази страница описва правилата за кодиране за библиотеките и приложенията на проекта Deeptown. Спазването на тези правила е не по-малко важно от качеството на кода: то повишава четливостта на кода от други хора. Неспазването на тези правила може да доведе до отказ за приемане на кода.

Разбира се, има изключения от всяко правило и никой не изисква от вас да следвате тези правила докрай. Но практиката показва, че кодът, проектиран в един стил, е по-лесен за четене и разбиране от хората, участващи в проекта. За разлика от много други проекти, нашите правила не са много строги и в тях са посочени само най-основните неща.

Първият раздел предоставя общи правила за всички езици за програмиране и маркиране; в следващите раздели те са посочени за различни езици.

Общи правила

Език и кодиране

За международни символи проектът използва UTF-8 кодиране. Можете да използвате низове на български и други езици директно в кода на програмата - за целта е необходимо да запазите изходния код на програмата в UTF-8 кодировка. Но не забравяйте, че това е лош стил: в една добра програма всички международни съобщения са във файлове с данни.

Подход за писане на код

Най-важното правило: кодът трябва да бъде лесен за четене и красив.

Deeptown е много голям проект, състоящ се от много модули. Тези модули са свързани един с друг и правилното функциониране на единия е невъзможно без другия. Следователно ние не приемаме код само за запис.

За да се окаже красив кодът, на първо място се нуждаете от творчески подход към написването му. Следователно ние не предоставяме никакви официални правила по този въпрос. Спорните ситуации ще се решават в дискусии.

Коментари

Обикновено, за да изпълни това условиедостатъчно е да напишете малки обяснения за всеки клас и метод в този клас.

Коментарите трябва да обясняваткакработи кодът, а некаквоправи. Отговорът на втория въпрос трябва да е в документацията, а не в кода; ние не използваме системи като doxygen в проекта за генериране на документация от код, защото вярваме, че документацията в кода претрупва кода и го прави труден за четене.

Коментар в началото на файла

Всеки изходен файл трябва да започва със следната информация:

Отстъп в кода

Използване на операторни скоби

Всички операторни скоби се поставят на нов ред; кодът, ограден в операторни скоби, е отстъпен с единица. Кодът започва на следващия ред след отварящата скоба. Изключение се прави за конструкции, при които тялото на операторските скоби се състои от не повече от 10 реда. В този случай е позволено да поставите скобата на отварящия оператор на същия ред като оператора, който я е "създал":

Освен това се прави специално изключение за конструкцията if. иначе:

Изключението се отнася и за конструкции, които не са твърде дълги.

Правила за K++ код

Правила за именуване

(с удебелен шрифт са отбелязани задължителни правила, останалите са желателни, но не са задължителни).

  1. Модулите са именувани в стил MyModuleName;
  2. Имената на файловете са точно същите като имената на модулите. Например модулът Proto::HTTP трябва да бъде във файла Proto/HTTP.kpp;
  3. Класовете са именувани в стил MyClassName, без префикси;
  4. Публичните методи и свойства са именувани в стила someMethodName;
  5. Аргументите на функцията са именувани в стила argument_name;
  6. Всички публични имена трябва да говорят, за предпочитане безсъкращения, но не твърде дълги. Приблизителното ограничение на дължината на името е 20 знака;
  7. Частните методи и свойства се наименуват подобно на публичните;
  8. Локалните променливи са именувани в стила variable_name (всички букви са малки, долна черта между думите);
  9. Полетата на класа се именуват подобно на локалните променливи, но с префиксаm_.

Този подход към именуване има много предимства. Той почти не използва префикси (които обикновено са досадни), но стилът на писане на имената на класове, методи и променливи е различен, което прави кода по-лесен за четене.

Имайте предвид, че ние изискваме спазване на правилата за именуване на публичните части на модула, но за имената на "вътрешна кухня" даваме само препоръки. Това се прави, за да се осигури еднаквост на интерфейсите.

Правила за C++ код

Този раздел е копиран от кодовия стандарт на самия Deeptown. Може някой да не харесва този стил, но така се е случило исторически. Ако има твърде много възражения, ще напишем скрипт, който ще конвертира един стил в друг. Но ще го направим централизирано. Сега този стил е възприет в проекта и holivars по този повод са много нежелателни.

Преносимост на кода

Целият код на проекта трябва да се компилира, изгражда и изпълнява на всяка система, било то Windows, Mac, UNIX, Solaris и други. Използването на библиотеки също е ограничено само от лицензионни споразумения и тяхната преносимост към други системи. В някои случаи се допускат изключения: кодът може да бъде написан в няколко версии за различни системи. Но в крайна сметка трябва да е възможно кодът да се изгради на всяка система.

Схеми за дерефериране

По-нататък следните дефиниции се използват за имената на различниобекти:

  • arbitrary- обектът може да бъде именуван произволно.
  • главна непрекъсната- обектът трябва да бъде наименуван с главни букви, думите да не се разделят една от друга. Например OBJECTNAME.
  • capital [separate]- обектът трябва да бъде именуван с главни букви, думите са разделени една от друга с долна черта: OBJECT_NAME.
  • линейно обединено,линейно [отделно]- по подобен начин: съответно име на обект и име_на_обект.
  • main- името трябва да започва с главна буква и всяка дума трябва да започва с главна буква. Останалите букви са малки: Име на обект.

Файлова структура от най-високо ниво

Целият код на проекта е дърво от подпроекти. Всеки подпроект е логически завършен модул, който може сам да се състои от подпроекти; или компилиран в програма, статична или динамична библиотека или скрипт; или накрая да съдържа и двете. Подпроектите се наименуват с помощта на схема за именуване с малки букви (понякога отделна) и се намират в директории, съответстващи на техните имена.

Така на всеки подпроект се присвоява неговият уникален идентификатор - това е пътят до подпроекта спрямо основната директория на проекта.

Дерефериране на файлове

Всички файлове в модула трябва да бъдат именувани с помощта на схемата за именуване с малки букви. Единствените изключения са изходните файлове, които съдържат реализации на някои класове - те съвпадат точно с имената на класовете. Това ще бъде обсъдено допълнително.

Разделяне на файлове в директории

Всички модулни файлове са разделени в директории, както следва:

  • всички публични включени файлове трябва да са в основната директория на модула;
  • всичковътрешните включени файлове трябва да са в поддиректориятаimpl;
  • всички изходни файлове трябва да са в директориятаsource.

Разделяне на функции и класове във файлове

Във всеки модул или част от него функциите и класовете са разделени на вътрешни – използвани само от този модул, и публични – експортирани от модула към „външния свят“.

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

Вътрешните функции и класове не трябва да се декларират в публични заглавни файлове и не трябва да се излагат на "външния свят" по никакъв начин.

Реализацията на всеки клас трябва да бъде поставена в отделен изходен файл, чието име е същото като името на класа.

Няма ограничения за разделянето на реализации на отделни функции във файлове.

Пространства от имена

Пазители на приобщаването

Всички заглавни файлове трябва да бъдат защитени от включена защита. Името на пазителя на включването се дава на следния модел: __PRFX_FILENAME_H_INCLUDED.

Тук PRFX е префиксът на модула и неговата част (вижте раздел 4.1), FILENAME е името на заглавния файл, изписано с главни букви.

Конвенции за именуване на обекти

Прилагат се следните правила за дерефериране:

  • Дефинициите на препроцесора са именувани с главни букви. В допълнение, всички дефиниции на препроцесора имат два префикса. Първият съответства на модула и неговата част (4 знака), вторият - на значението на дефиницията. Префиксите са разделени един от друг и от името с долна черта. Пример:SEST_IBS_LOADED(Soung Engine, модул STreaming; състояние на индексния буфер).
  • Интерфейсите (класове, в които всички методи са абстрактни) се именуват според стандартната схема,префиксI(ISomeName).
  • Класовете са именувани според стандартната схема, префиксC(CClassName).
  • Структурите се именуват според стандартната схема (StructName).
  • Функциите и методите на класа също се именуват според стандартната схема.
  • Частните полета и локалните променливи се именуват произволно.
  • Публичните полета на класовете и аргументите на функцията се именуват по следната схема: името на променливата се изписва по основната схема; добавя се префикс, съответстващ на типа променлива (pszIndexName). Префиксът m_ (m_pszIndexName) също се добавя към публичните полета на класа.

Префикси за стандартни типове:

  • [без знак] int: i, u, n
  • неподписан символ, байт: b
  • char:c
  • char*, char[] (в смисъл на низ): sz
  • [неподписано] кратко, дума: w
  • dword:dw
  • qword: qw
  • всеки указател :p

За нестандартни типове префиксът се избира според името на типа. Дължината на префикса е от един до два знака.

Правила за проектиране на оператори

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

  1. За всяко изявление се отделя нов ред.
  2. Скобите не се разделят с интервали.
  3. Максималната дължина на низа е 80 знака. Ако се изисква повече, остатъкът от оператора се обвива на следващия ред и към него се добавя допълнителен отстъп (остатъкът).
  4. Ако тялото на оператор if или цикъл се състои от един оператор, не се поставят скоби и операторът се записва на нов ред с допълнителен отстъп.
  5. Няма ограничения за използване на пространствата.

Забранени дизайни

Използването на командата goto е забранено. Единственото изключение е излизане от цикли с множество нивагнездене.

До < . >докато(. ); не се препоръчва да се използва, особено ако тялото на цикъла е повече от 10 реда.