Стандарт оформления исходного текста программ на языке Си (Разрабатывается методичка для студентов)

altlogic · Сообщение **altlogic** » 12.05.2009 09:18

Здравствуйте!

С недавних пор преподаю дисциплину "Микропроцессорные системы" в университете. Встал вопрос о понимании студентами "хорошо" и "плохо" написанной программы. Имея некоторый скромный опыт написания программ я могу сказать как не стоит оформлять программу, а как стоит. Но ведь до этого я изучал технологии программирования, разбирался в чужих исходниках и наконец сам писал программы. Вроде бы и правила написания программ просты: должное форматирование, разбиение на модули, присвоение осмысленных имён переменным и функциям и прочее. Но я решил упорядочить эту информацию в одном документе. Конкретно мне это видится методическим указанием или инструкцией по оформлениюю исходных текстов программ на языке Си [для встроенных систем].

Может кто чем поделиться? Ссылки на Кернигана, Ричи, Шилдта и других монстров Си конечно будут приняты, но я хочу получить выжимку из них, скажем листов на 15-20 14м шрифтом А4.

Сообщение **Portnov** » 12.05.2009 10:44

Например, можно спокойно брать за основу стандарт оформления исходников для ядра linux: http://lxr.linux.no/linux/Documentation/CodingStyle. По мере надобности убрать оттуда вещи, специфичные для ядра (типа 'printing kernel messages') - и всё.

altlogic · Сообщение **altlogic** » 12.05.2009 10:58

Спасибо, как то я не догалася погуглить на английком языке. Linux kernel coding style всё же документ для более частного применения. Собственно на английском источников то масса. А может у кого-нибудь есть руководящие документы на русском? Очень понравился документ GNU coding standards. Пожалуй его пятая глава - это именно то, что мне нужно. Но вот найти бы ещё перевод этого документа.

altlogic · Сообщение **altlogic** » 12.05.2009 11:48

Кто ищет, тот всегда найдёт - http://www.opennet.ru/docs/RUS/coding_standard/

NickLion · Сообщение **NickLion** » 12.05.2009 17:30

ИМХО. Не назвал бы это красивым оформлением кода: http://www.opennet.ru/docs/RUS/coding_stan...standard-8.html

Сообщение **Portnov** » 12.05.2009 18:39

NickLion
Там приведены доводы, почему такое оформление имеет смысл. Кроме того, оно используется в большом количестве проектов, и определённо стоит его придерживаться, если есть шансы что ваш код в один из них попадёт. Для новых проектов также стоит использовать те же стандарты, чтобы программистам, писавшим для других проектов, не приходилось переучиваться.

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

Denjs · Сообщение **Denjs** » 12.05.2009 18:41

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

Cкачайте тот-же IDE Eclipse - там в настройках "Prefences > C/C++ > Code Style "приводится список c примерами оформления. Покликайте, посомтрите как меняется код открытый в текущем едиторе, по названиям - ищите в сети.

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

altlogic · Сообщение **altlogic** » 13.05.2009 03:38

Ну вот, чего и следовало ожидать. Одному нравится оформлять код так, другому иначе. Я сам пишу в IDE AVR32Studio, она основана на eclipce. Мне самому больше всего нравится стиль оформления GNU. Хотя, то что приведено по ссылке http://www.opennet.ru/docs/RUS/coding_stan...standard-8.html несколько не соответствует и моим представлениям о хорошем коде. В поиске нашёл стандарты различных предприятий по оформлению кода. А вот то, что стиль оформления кода и наименования переменных - это разные вещи - согласен. Это нужно будет обязательно разделить.
За время летней практики постараюсь подготовить стандарт оформления исходного кода. А потом и с его публикацией можно будет подумать. Наверное у людей работающих в команде интерес к такому документу существует.
Кстати говоря существуют и программы, которые форматируют код в соответствии с заданными правилами (методичкой

. Тот же eclipse например.

drBatty · Сообщение **drBatty** » 13.05.2009 07:18

altlogic писал(а): ↑
13.05.2009 03:38
Кстати говоря существуют и программы, которые форматируют код в соответствии с заданными правилами

... что-бы эти программы нормально работали, необходимо придерживаться какого-либо стиля ещё во время написания... Иначе эти программы только всё испортят. На самом деле это просто конвертеры стиля A в стиль B, а вовсе не "МУСОР" => стиль A

NickLion · Сообщение **NickLion** » 13.05.2009 11:43

Portnov писал(а): ↑
12.05.2009 18:39
Там приведены доводы, почему такое оформление имеет смысл. Кроме того, оно используется в большом количестве проектов, и определённо стоит его придерживаться, если есть шансы что ваш код в один из них попадёт. Для новых проектов также стоит использовать те же стандарты, чтобы программистам, писавшим для других проектов, не приходилось переучиваться.

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

В большом - не значит во всех. Навскидку из ядра линукса:

Код:


	if ((GET_ASIC_REV(tp->pci_chip_rev_id) == ASIC_REV_5701)) {
		static struct tg3_dev_id {
			u32	vendor;
			u32	device;
		} bridge_chipsets[] = {
			{ PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_PXH_0 },
			{ PCI_VENDOR_ID_INTEL, PCI_DEVICE_ID_INTEL_PXH_1 },
			{ },
		};
		struct tg3_dev_id *pci_id = &bridge_chipsets[0];
		struct pci_dev *bridge = NULL;

		while (pci_id->vendor != 0) {
			bridge = pci_get_device(pci_id->vendor,
						pci_id->device,
						bridge);
			if (!bridge) {
				pci_id++;
				continue;
			}
			if (bridge->subordinate &&
			    (bridge->subordinate->number <=
			     tp->pdev->bus->number) &&
			    (bridge->subordinate->subordinate >=
			     tp->pdev->bus->number)) {
				tp->tg3_flags3 |= TG3_FLG3_5701_DMA_BUG;
				pci_dev_put(bridge);
				break;
			}
		}
	}

Как видим { стоит справа от оператора, а не на новой строке. Я тоже так пишу.

Далее из KDE:

Код:

    void
  AsyncCDDBPLookup::read()
  {
    switch ( state_ )
    {
      case WaitingForGreeting:

        if ( !parseGreeting( readLine() ) )
        {
          result_ = ServerError;
          doQuit();
          return;
        }

        doHandshake();

        break;

      case WaitingForHandshake:

        if ( !parseHandshake( readLine() ) )
        {
          result_ = ServerError;
          doQuit();
          return;
        }

        doProto();

        break;

      case WaitingForProtoResponse:

        // Ignore the response for now
        readLine();

        doQuery();

        break;

      case WaitingForQueryResponse:
          result_ = parseQuery( readLine() );

          switch ( result_ )
          {
            case Success:
              requestCDInfoForMatch();
              break;

            case MultipleRecordFound:
              state_ = WaitingForMoreMatches;
              break;

            default: // Error 
              doQuit();
              return;
          }

        break;

      case WaitingForMoreMatches:
        {
          QString line = readLine();

          if (line.startsWith("."))
            requestCDInfoForMatch();
          else
            parseExtraMatch( line );
        }

        break;

      case WaitingForCDInfoResponse:
        {
          Result result = parseRead( readLine() );

          if ( Success != result )
          {
            result_ = result;
            doQuit();
            return;
          }

          state_ = WaitingForCDInfoData;
        }

        break;

      case WaitingForCDInfoData:
        {
          QString line = readLine();

          if (line.startsWith("."))
          {
            parseCDInfoData();
            requestCDInfoForMatch();
          }
          else
            cdInfoBuffer_ << line;
        }

        break;

      case WaitingForQuitResponse:

        state_ = Idle;

        char c;
        while ( socket_->bytesAvailable() )
          socket_->getChar(&c);

        close();

        emit finished( result_ );

        break;

      default:

        break;
    }
  }

Скобочки стоят на новой строке, но в той же колонке, что и оператор.

И что мы видим в примере кода из http://www.opennet.ru/docs/RUS/coding_stan...standard-8.html ?

Код:

    if (x < foo (y, z))
       haha = bar[4] + 5;
     else
       {
         while (z)
           {
             haha += foo (z, z);
             z--;
           }
         return ++x + bar ();
       }

if, else - в разных колонках, сдвинуты и сами скобочки { и блок внутри них.

ИМХО, это некрасиво.

Сообщение **Portnov** » 13.05.2009 15:03

Стиль, принятый в ядре, отличаются от GNU-стиля (вон я вверху ссылку давал).

Denjs · Сообщение **Denjs** » 13.05.2009 16:27

NickLion писал(а): ↑
13.05.2009 11:43
И что мы видим в примере кода из http://www.opennet.ru/docs/RUS/coding_stan...standard-8.html ?

Код:
if (x < foo (y, z)) haha = bar[4] + 5; else { while (z) { haha += foo (z, z); z--; } return ++x + bar (); }

if, else - в разных колонках, сдвинуты и сами скобочки { и блок внутри них.

ИМХО, это некрасиво.

УХТЫ?! это ещё кто-то изоборел?!
я думал я один так код оформляю ))))

да насчет красивости - код должен быть ЧИТАЕМ! а не красивым.

В последнем примере - когда вы бежите глазами по коду - вас часто (ОЧЕНЬ!) интересует "где там следующая инструкция за "while""
- для этого - ваш глаз просто скользит по вертикали до первого препятствия :

Код: Выделить всё

         while (z)
              {
                haha += foo (z, z);
                z--;
              };
         return ++x + bar ();

Глаз не должен "цепляться" за первую скобку открывающую, потом закрывающую и "считать их".
Вот это : действительно не красиво потому что ТРУДНО ЧИТАЕМО - глаз должен остановиться 2 раза на одной скобочке, понять что это не следующий оператор, потом на второй скобочке, понять что это не оператор, и только потом найти то что нужно - "наконец оператор"(!):

Код: Выделить всё

         while (z)
         {
             haha += foo (z, z);
             z--;
         }
         return ++x + bar ();

Аналогично не читаемо из первого примера (ядро линукс)

Код: Выделить всё


         if (bridge->subordinate &&
            (bridge->subordinate->number <=
              tp->pdev->bus->number) &&
            (bridge->subordinate->subordinate >=
              tp->pdev->bus->number)) {
                   tp->tg3_flags3 |= TG3_FLG3_5701_DMA_BUG;
                   pci_dev_put(bridge);
                   break;
           }

здесь в if важно сразу видеть где если условие, а где операторы.
"tp->tg3_flags3 |= TG3_FLG3_5701_DMA_BUG;" коспринимается как ещё одна строчка условия по крайней мере когда начинаешь читать это.
и только черед полсекунды , добежав до неожиданно закрывающейся скобки.... я наконец осознаю что "йомайо... где-то там на краю зрительного пространства оказывается(!!!!) действительно БЫЛА скобочка... только блин.. ГДЕ?!".
Аналогично вердикт - "не читаемо".

ИМХО )))

PS: Описанное выше - все моё. документ по ссылке не читал.
Стиль кода который я использую это фактически "обретенный мною самостоятельно".
Ниоткуда я его не вычитывал, и никогда ему не учился. По крайней мере ничего такого не помню.
Использую аналогичный синтаксис практически ещё со времен далеких win95, TurboC, TurboPascal .
Потому можете считать что это - мой, найденный опытным путем "best practice".

NickLion · Сообщение **NickLion** » 13.05.2009 22:03

Portnov писал(а): ↑
13.05.2009 15:03
Стиль, принятый в ядре, отличаются от GNU-стиля (вон я вверху ссылку давал).

Вот и я про то, что предлагать основные стили на выбор - K&R, GNU, BSD, etc...

Denjs писал(а): ↑
13.05.2009 16:27
да насчет красивости - код должен быть ЧИТАЕМ! а не красивым.
...
В последнем примере - когда вы бежите глазами по коду - вас часто (ОЧЕНЬ!) интересует "где там следующая инструкция за "while""
- для этого - ваш глаз просто скользит по вертикали до первого препятствия :
...
Глаз не должен "цепляться" за первую скобку открывающую, потом закрывающую и "считать их".[i]
Вот это : действительно не красиво потому что ТРУДНО ЧИТАЕМО - глаз должен остановиться 2 раза на одной скобочке, понять что это не следующий оператор, потом на второй скобочке, понять что это не оператор, и только потом найти то что нужно - "наконец оператор"(!):
...
Аналогично не читаемо из первого примера (ядро линукс)
...
здесь в if важно сразу видеть где если условие, а где операторы.
"tp->tg3_flags3 |= TG3_FLG3_5701_DMA_BUG;" коспринимается как ещё одна строчка условия по крайней мере когда начинаешь читать это.
и только черед полсекунды , добежав до неожиданно закрывающейся скобки.... я наконец осознаю что "йомайо... где-то там на краю зрительного пространства оказывается(!!!!) действительно БЫЛА скобочка... только блин.. ГДЕ?!".
Аналогично вердикт - "не читаемо".

Под красивым я имею в виду именно читабельный, а не эстетическое восприятие. Лично мне проще "ловить" именно закрывающую скобку, а не следующий оперетор. Сдвиг else на следующую колонку - вообще необосновано, ИМХО, его можно легко пропустить при поиске. В случае многострочного условия в if/while/function definition/etc я переношу скобочку на новую строку, кстати.

PS Love&Peace

Я не утверждаю, что этот стиль плох ВООБЩЕ (хороший-плохой - понятия в принципе относительные). Он плох ДЛЯ МЕНЯ. Я это все к тому веду, что если составлять учебно-методическое пособие, то следует туда внести описания основных стилей оформления кода, а не одного. Потому что у каждого человека своя психология, что одному - просто и легко, то другому непонятно. Так мне легче всего читать мой стиль (шлифовавшийся достаточно долго), он похож на K&R, но есть отличия. Denjs и Portnov, я так понимаю, сторонники GNU стиля. Есть сторонники стиля Страуструпа. Каждому свое.

cy6erGn0m · Сообщение **cy6erGn0m** » 13.05.2009 22:48

О да, это дело вкусов. На мой взгяд лишние отступы как в стиле GNU это просто злодейство

Так что полностью согласен с NickLion.

+1 за K&R.

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

altlogic · Сообщение **altlogic** » 14.05.2009 03:35

drBatty писал(а): ↑
13.05.2009 07:18
... что-бы эти программы нормально работали, необходимо придерживаться какого-либо стиля ещё во время написания... Иначе эти программы только всё испортят. На самом деле это просто конвертеры стиля A в стиль B, а вовсе не "МУСОР" => стиль A

В том то и дело, что тот же elipse делает из мусора читаемый код. В частности форматирует скобочки {} так, как задано в правилах
Было:

Код: Выделить всё

int b ,  c[5];
void NTRXASInitStart(){
}
void NTRXASRxReceive(){}

стало

Код: Выделить всё

int b, c[5];
void NTRXASInitStart()
{
}
void NTRXASRxReceive()
{
}

NickLion писал(а): ↑
13.05.2009 22:03
Я это все к тому веду, что если составлять учебно-методическое пособие, то следует туда внести описания основных стилей оформления кода, а не одного. Потому что у каждого человека своя психология, что одному - просто и легко, то другому непонятно. Так мне легче всего читать мой стиль (шлифовавшийся достаточно долго), он похож на K&R, но есть отличия. Denjs и Portnov, я так понимаю, сторонники GNU стиля. Есть сторонники стиля Страуструпа. Каждому свое.

У студентов есть свой стиль программирования - "БЕЗ_СТИЛЯ":)

NickLion · Сообщение **NickLion** » 14.05.2009 08:55

Да, скобочки и отступы многие берут. Например Artistic Style - http://astyle.sourceforge.net/. Но уже в Вашем примере видно, что пустую строчку между функциями eclipse не осилил. А еще часто вижу такое:

Код: Выделить всё

if(blah-blah)
{code begins here
...
ends here;}

без отступов, без переносов... Осилит?

altlogic · Сообщение **altlogic** » 14.05.2009 09:38

NickLion писал(а): ↑
14.05.2009 08:55
Да, скобочки и отступы многие берут. Например Artistic Style -Но уже в Вашем примере видно, что пустую строчку между функциями eclipse не осилил.

Не осилил

Код: Выделить всё

if(blah-blah)
{    code begins here
    ...
    ends here;}

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

Сообщение **Portnov** » 14.05.2009 10:26

altlogic писал(а): ↑
14.05.2009 03:35
У студентов есть свой стиль программирования - "БЕЗ_СТИЛЯ":)

Ага, есть ещё другой стиль - 'в одну строчку сколько влезет' :)

Код: Выделить всё

program test;
var x,y: integer; z:double;
begin writeln('Vvedite chislo'); readln(x);z:=x*2
...
end.

:)

Denjs · Сообщение **Denjs** » 14.05.2009 10:44

Portnov писал(а): ↑
14.05.2009 10:26
Ага, есть ещё другой стиль - 'в одну строчку сколько влезет'

Это частный случай) подвид)

Denjs · Сообщение **Denjs** » 15.05.2009 14:17

Вот ещё ссылко по теме:
http://habrahabr.ru/blogs/development/59570/

drBatty · Сообщение **drBatty** » 15.05.2009 15:33

altlogic писал(а): ↑
14.05.2009 03:35
В том то и дело, что тот же elipse делает из мусора читаемый код. В частности форматирует скобочки {} так, как задано в правилах
Было:

да, конечно. Hello world может и осилит(и то не всегда), в реальном коде только всё испортит

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

RasenHerz · Сообщение **RasenHerz** » 15.05.2009 19:07

Сам предпочитаю стиль 1TBS , но правда бывают некоторые неудобства:

Код: Выделить всё

if ((pthread_mutex_init(&work_list.lock, NULL) != 0) ||
    (pthread_mutex_init(&dead_list.lock, NULL) != 0) ){
    printf("Failed to init mutex.\n");
    pthread_exit(SERV_ERR_MUTEX);
}

отступы и скобки расставлены NetBeans,
в таком слачае использую стиль Алмена:

Код: Выделить всё

if ((pthread_mutex_init(&work_list.lock, NULL) != 0) ||
    (pthread_mutex_init(&dead_list.lock, NULL) != 0) )
{
    printf("Failed to init mutex.\n");
    pthread_exit(SERV_ERR_MUTEX);
}

как вы избегаете подобных ситуаций в оформлении кода?

NickLion · Сообщение **NickLion** » 16.05.2009 00:27

RasenHerz
Да в принципе, так же. Или пытаюсь сократить условие (но такая возможность бывает нечасто). Бывает, еще так пишу (но реже):

Код: Выделить всё

if(
    condition_line_1
    condition_line_2
    ...
) {
    body
    ....
}

altlogic · Сообщение **altlogic** » 16.05.2009 04:13

drBatty писал(а): ↑
15.05.2009 15:33
да, конечно. Hello world может и осилит(и то не всегда), в реальном коде только всё испортит примеры выше.
Хотя можете поступить проще - возьмите кусок любого реального кода, из любого проекта, и отформатируйте...

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

unixforum.org

Стандарт оформления исходного текста программ на языке Си (Разрабатывается методичка для студентов)

Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си

Re: Стандарт оформления исходного текста программ на языке Си