Документация к программе.

[ZeroCount]

Не нашел, какой раздел лучше подходит для создания этой темы, решил здесь.

Как должна выглядеть документация к программе? Что в ней должно содержаться?
Буду рад, если кто-нибудь вкратце опишет или пошлет пример.

[Obey-Kun]

Документация делится на 3 части. Первые 2 части нужны программистам, последняя — пользователям.

Часть 1 — документация API. Должно отвечать на вопрос «Что это делает?». Это описание классов, методов, полей и т.п. Такая документация должна быть наиболее полной. Для неё, как правило, используют инструменты вроде Doxygen, которые позволяют встраивать документацию в код.
Наример, вот такая фигня (C++, приватные поля класса SoilBlock):

    /// Массив размеров блока (\f$ r \f$). Элементы соответствуют осям x, y и z
    std::vector<double> m_dimensions;
    
    /// Шаг по времени, делённый на объём блока (\f$ \tau/\nu \f$)
    double m_time_step_per_volume;
    
    /// Энтальпия (\f$ H \f$)
    double m_enthalpy;
    
    /// Температура (\f$ T \f$)
    double m_temperature;
    
    /// Относительный объём талой фазы (\f$ V \f$)
    double m_thawed_part;
    
    /// Теплоёмкость талого и мёрзлого грунта (\f$ C_{th} \f$ и \f$ C_f \f$)
    Phased m_capacity;
    
    /** Теплопроводность талого и мёрзлого грунта
        (\f$ \lambda_{th} \f$ и \f$ \lambda_f \f$) */
    Phased m_conductivity;

    /** Эффективная теплопроводность в минус первой степени \f$ 1/\lambda \f$.
        @see calcCondition() */
    double m_ie_conductivity;

Даёт вот такого вида красоту (это кусок html странички, созданной doxygen): http://img819.imageshack.us/img819/9397/28732417.png
Вот вам пример документации одного из классов огромного проекта, сгенерированного при помощи Doxygen: http://doc.qt.nokia.com/4.7/qpoint.html

Часть 2 — документация к коду. Должно отвечать на вопрос «Как это работает?». Это пояснения к работе кода.
Вот, например:

    // передаём клик в стандартный обработчик, чтобы тот передал его в сцену
    QGraphicsView::mousePressEvent(event);
    
    // если сцена приняла событие, оно нам ни к чему
    if(event->isAccepted()) {
        return;
    }
    
    if(event->button() == Qt::RightButton) {
        startHandScroll(event->globalPos());
        return;
    }

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

Часть 3 — документация конечного пользователя. Её имеют взрослые программы (правда, не всегда). Вот пример.



Всё. Но осталось рассказать о важной вещи. Неотъемлемой частью документации к API и к коду является следование хорошим правилам именования. Например:

class Point
{
    public:
        Point(int x, int y);
        int x() const;
        int y() const;
        void setX(int x);
        void setY(int y);
        bool isNull() const;
    private:
        int m_x;
        int m_y;
};

Вот видите. Даже без определения методов и без всяких комментариев сразу понятно, что тут что делает. То есть код как бы документирует сам себя. Для такого эффекта достаточно следовать таким правилам (они могут различаться в разных проектах, я привёл те, что использую сам):

• Классы. Писать как SomeTextHere. Названия должны быть существительными. Например: Point, ImageGallery, BaseballBat.
• Методы (и прочие функции). Писать как someTextHere. Названия должны быть глаголами для void, прилагательными для bool и существительными для прочего. Примеры есть в коде выше: int x(), void setX(), bool isNull(). Также можно использовать специальные названия для конвертаторов, начинающиеся на to, например std::string toString() (возвращает представление класса строкой).
• Переменные. Писать как some_text_here. Аналогично методам: int x, int y, bool is_null, bool has_color, Point left_point. Что важно, поля в классах следует именовать как-то по-особому, например начиная с «m_»: m_x, m_y, m_is_null и т.д. Это позволит с первого взгляда понять, что мы работаем именно с полем, что избавит от возможных ошибок, а также от проблемы Variable shadowing.
• Макросы. Вообще, в хороших местах макросов избегают. И каждый раз когда вы пишите макрос, Обама убивает младенца. Но раз вам не жалко младенцев, пишите SOMETEXTHERE.

Очень хорошим примером именования методов и классов является Qt. http://doc.qt.nokia.com/4.7/classes.html — потыкайте по классам, полюбуйтесь названиями.

Ну нифига ж себе я накатал...

[ZeroCount]

Вроде понятно. Спасибо.

[Obey-Kun]

Немного обновил текст, см. поправку в части 1 и добавленный в конце текст.

[p51x]

А есть еще ГОСТы.....

[Obey-Kun]

А что там насчёт ГОСТов?

[Obey-Kun]

Забыл добавить. В коде это есть, но вслух я этого не говорил. Для поля m_some_value геттер будет someValue() const, а сеттер — setSomeValue(...)