Конвенция/стандарты кодирования C

[Nick]

День добрый!
Интерисует следущие какой стандарт наибоелее предпочтителен в C и по чему.
Я смотрел Dennis Ritchie&Brian Kernighan,  но  ответа как-то не нашел

Мне показался удобным такой вариант:

/*******************************************************************
** Name:    MGCGILink
** Descr:    Inserts a url-style link in a web page
** Params:    URL = The url for the link
**            Text = Text that describes the URL.
** Returns: MGCGI_ERROK, or error code upon failure
** Author:    MG 10/9/97
** Type:    Output/Components and Controls
********************************************************************/
int MGCGILink( char *URL, char *Text )
{
    char *TmpText;
   
    if( (TmpText = MGCGIConvertToHTML( NULL, Text )) == NULL )
        return( MGCGI_ERRNOMEM );

    fprintf( MGCGIDest, "<A HREF=\"%s\">%s</A>", URL, TmpText );
    free( TmpText );
    return( MGCGI_ERROK );
}
Может быть кто-нибудь даст сцылочку на этот стандарт кодирования или может поделится своими предпочтениями

[darkelf]

Если Вы про отступы, то, имхо, это похоже на стиль Олмана, а если про пробелы между скобками, то, к сожалению, такого стиля не знаю.

[Dale]

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

Если речь о разработке, для меня предпочтителен стандарт MISRA. Почему - следует из определения.

Если речь об оформлении, то объективных причин для выбора нет, это исключительно холиварное направление без малейшего конструктива. Опытные люди руководствуются железным правилом: не так уж важно, какой из вариантов будет выбран, главное, чтобы его придерживались все члены команды во всех файлах проекта. Мудрые люди вообще не заморачиваются подобными пустяками, поскольку пользуются инструментами наподобие GNU Indent, которые позволяют быстро оформить любой синтаксически корректный код на C в любом стиле. Отдайте тупую работу компьютеру и думайте о вещах, которые действительно стоит обдумывать.

[Nick]

2Dale, Спасибо. GNU Indent - попробовал, удобная утилита.
Просто хотелось понять как лучше документировать код.

[RXL]

Лучшая документация кода - читаемый код!

[Джон]

Просто хотелось понять как лучше документировать код.

Нда... изначально в вопросе темы это было как-то трудно уловить.

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

[Dale]

Просто хотелось понять как лучше документировать код.

Тогда вы уж очень издалека зашли. Причем не у меня одного возникло такое впечатление:

Нда... изначально в вопросе темы это было как-то трудно уловить.

Как общее правило воспользуйтесь советом RXL:

Лучшая документация кода - читаемый код!

Как способ достижения этой цели используйте концепцию "грамотного кодирования" Дональда Кнута. Помогут в выработке стиля также рекомендации Стивена Макконнелла ("Совершенный код" и др.), "дядюшки Боба" Роберта Мартина ("Чистый код" и др.) и множество других книг на эту тему, сейчас их предостаточно. Некоторые из них найдете на моей "Книжной полке".

Сторонники agile подхода считают, что очень хорошую документацию представляют собой тесты (особенно если разработка ведется через TDD/BDD/ATDD и иже с ними). Я с ними полностью солидарен.

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

Изучайте и применяйте паттерны. Они прекрасно документированы и известны профессионалам. Достаточно сказать "здесь использован паттерн такой-то", и можно дальше не комментировать, все и так понятно. Главное - применять их осознанно (иначе получится собачий цирк наподобие того, который недавно устроил один из новичков под видом паттерна "Декоратор").

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

Если посмотрите на проблему еще ширше, выяснится, что кодирование - не самая сложная часть разработки (как укладка кирпичей не есть суть архитектуры, хотя от качества укладки, конечно, сильно зависит качество здания в целом). Понадобится документировать не только сам код, но и требования заказчика, и архитектуру решения, которая должна обеспечить воплощение этих требований. Тут весьма кстати придется UML и архитектурная модель "4+1".

Остается для меня непознанным единственный вопрос: при чем тут Unix?