Рекомендуемые правила оформления кода

[Ponkole]

Многие опытные программисты форума частенько жалуются на плохую читаемость кода. Конечно же каждый программист обладает так называемым "почерком" (стилем программирования). Но, согласитесь, у некоторых очень неразборчивые "почерки". Предлагаю тем, кто жалуется, в этой теме тезисно изложить рекомендуемые правила(от себя или где - нибудь общепринятые).

[Alex11223]

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

По этой причине и существуют Кодинг Гайдлайны у проектов.

[Вадим Мошев]

Тема очень хорошая, ИМХО. Сам хотел обсудить оформление кода. У меня за время писания когда, можно сказать, выработался свой почерк... позже расскажу...

[Utkin]

1. Практически каждая строка должна иметь поясняющий комментарий (кроме совсем очевидных, вроде end или операторных скобок).
2. Отступы в стиле Олмана - http://ru.wikipedia.org/wiki/%CE%F2%...E0%ED%E8%E5%29
3. Перед функцией/методом/процедурой обязательно:
а) Зачем нужна эта функция/метод/процедура
б) Краткая расшифровка всех входящих параметров
в) Иногда расшифровка результатов (например -1 в случае неверных входящих параметров).
4. Разделяю все методы, классы и прочие важные функциональные единицы программы строкой состоящей из одних слешей типа:
////////////////////////////////////////////////////////////////////////////////////////////////
Ну это на вскидку, может и еще чего делаю . Собственно конкретные детали не так уж и важны, главное чтобы оформление кода вообще имело место.

[ImmortalAlexSan]

C/C++/C#
1. Параметры функции именую, начиная с "p" : pParameter и т.д.
2. Внутренние переменые функций именую, начиная с "_" _Data и т.д.
3. Свойства класса именую с большой буквы.
4. Поля класса именую с маленькой буквы.
5. Именование функций, делегатов, событий и прочего для меня не так важно. все они с большой буквы. Интуитивно пониманию по ключевым словам в имени.
Это позволяет мне лучше ориентироваться в коде.
Касательно разметки:
Использую стиль Олмана.
Остальное что я тоже делаю, написал Уткин.
Очень долго свой подход разрабатывал, очень удобен и очень к нему привык.

[Bustle]

Как документировать код
Пример:

<?php

/**
 *
 * Описание файла
 *
 * @name значение
 * @version значение
 * @author значение
 * @since dd.mm.yyyy hh:mm
 *
 */

/**
 *
 * myFunction()
 *
 * Описание функции
 *
 * @author значение
 * @param array $Params
 * @return string
 *
 */
function myFunction($Params)
{
     return $Value;
}

/**
 * myClass
 *
 * Описание класса
 *
 * @access public
 * @author значение
 * @since dd.mm.yyyy hh:mm
 */
class myClass
{
    /* Const */
    const MYCONST = 1;
    /* Private *
    private static $_PrivStatic = 2;
    private $_PrivNonStatic = 3;
    /* Protected */
    protected static $_ProtStatic = 4;
    protected $_ProtNonStatic = 5;
    /* Public */
    public static $pubStatic = 6;
    public $pubNonStatic = 7;

    
    /**
     *
     * _PrivStaticFunc()
     *
     * Описание метода
     *
     * @access private
     * @static
     * @author значение
     * @param mixed $Params
     * @return mixed
     *
     */
    private static function _PrivStaticFunc($Param)
    {
    }

    /**
     *
     * PubFunc()
     *
     * Описание метода
     *
     * @access public
     * @author значение
     * @param array $Params
     * @return mixed
     *
     */
    public function pubFunc(array $Param = array())
    {
    }
}

Стиль:
- Табуляция 4 пробельных символа (именно пробельных символа, а не знак табуляции)
- Примеры оформления:

if ($xX === 1)
{
    // делаем что-то
    $yY = myFunc($Xx);
}
else
if ($xX === 2)
{
    // делаем что-то
}
else
{
    // делаем что-то
    $xX = myFunc(1, 3, 4, 10, 'hello');
    if ($xX == 1 && $yY == 'world')
    {
    }
}

function myFunc($Vv)
{
    $aA = array($vV);
    foreach($aA as $kK => $vV)
    {
        // что-то делаем
    }
    switch($aA)
    {
        case 1 :
        {
            break;
        }
        case 2 :
            break;
    }
}

- Желательно писать как можно короче
- Стараться умещать строку кода по ширине до 80 символов, на крайний случай до 120
- Названия переменных, классов, функций, методов и т.п. должны отражать суть, но не быть слишком длинными и не слишком короткими

[_-Re@l-_]

2. Отступы в стиле Олмана - http://ru.wikipedia.org/wiki/%CE%F2%...E0%ED%E8%E5%29

Что-то меня совсем не торкнули отступы на картинке по вашей ссылке.

[Utkin]

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

[Аватар]

Возможно стиль отступов и не определяющий (если нет особых требований привередливого заказчика), главно что бы они вообще были, и все ПО оформлено в одном стиле. В Delphi тоже без отступов читать код очень тяжело, другой раз на форуме выложат 10 строк кода без отступов, не только читать, но и смотреть противно

[Пепел Феникса]

С++/C#
1)применяю стиль Олмана(1 таб, размером в 4 пробела).
2)у параметров у методов обычно ставлю нижнее подчеркивание, но не всегда, а обычно только тогда когда конфликт с именем поля(причем для списка инициализации)
3)поля пишу с малой буквы(обычно всегда private)
4)имена классов с большой буквы, и чтоб понятные были.*
5)обязательно использую namespace.*
6)в хидерах никаких using.
7)методы пишу с большой буквы(Scan, Clean)
но get/set-методы чаще пишу с малой(getData)

Делфи:
1)отступы по одному пробелу
2)классы как положенно с Т, предрекая имя класса префиксом
3)поля предрекаю F<имя>
4)методы с большой буквы(LoadFromFile)

*

phL::LexicalScanner::Scanner