CommentStyle
Предлагаю комменты писать в формате доксигена (См. http://doxygen.org). Это несложно и дисциплинирует, а доксиген легко выдает красивые доки, приятно радующие глаз ревьювера, работодателя и ваших коллег. )
В начале файла пишем:
//{=================================================================================
//! @file SolveSquare.cpp
//! @date 2013-09-22 21:01
//! @author Ilya Dedinsky <[email protected]>
//!
//! Решение квадратного уравнения с честным разбором частных случаев.
//!
//! @par Условие задачи
//! Программа вводит 3 коэффициента квадратного уравнения. Надо вывести
//! количество его корней (-1 в случае бесконечного их к-ва) и сами корни.
//! Условие, разумеется, копируется оттуда, откуда взята задача, или
//! пишется самостоятельно.
//!
//! @warning Круглые уравнения не вводить!
//}=================================================================================
Строчки, помеченные как //! - это документирующий коммент, его распознает и обрабатывает доксиген.
В остальные комменты он не лезет.
//} и //{ - не доксигенные комменты, но для тех, кто пишет в кодблоксе, это определит группу сворачивания - и документирующий коммент будет легко свернуть (плюсик-минусик слева в начале коммента).
Не забываем менять дату и время, это полезно для выявления ошибочных посылок старых версий.
Желательно автоматизировать вставку правильной даты и времени, чтобы не ошибаться.
Можно ввести номер версии (доксиген тег @version), тогда тоже не забываем ее менять.
Перед каждой константой пишем:
//! Значение, возвращаемое SolveSquare в случае бесконечно большого количества корней.
const int SS_INFINITE_ROOTS = -1;
или так:
const int SS_INFINITE_ROOTS = -1; //!< Значение, возвращаемое SolveSquare в случае бесконечно большого количества корней.
Перед каждой функцией пишем:
//{=================================================================================
//! SolveSquare - solve a square or linear equation specified by its coefficients.
//!
//! @param a Equation a-coefficient
//! @param b Equation b-coefficient
//! @param c Equation c-coefficient
//! @param[out] x1 1st root of equation, if exist (if not, value will be unchanged)
//! @param[out] x2 2nd root of equation, if exist (if not, value will be unchanged)
//!
//! @return Number of roots or zero if none, -1 if infinite number of roots
//!
//! @note Calculation precision is considered to be DBL_EPSILON.
//}=================================================================================
или так:
/** ********************************************************************************
SolveSquare - solve a square or linear equation specified by its coefficients.
@param a Equation a-coefficient
@param b Equation b-coefficient
@param c Equation c-coefficient
@param[out] x1 1st root of equation, if exist (if not, value will be unchanged)
@param[out] x2 2nd root of equation, if exist (if not, value will be unchanged)
@return Number of roots or zero if none, -1 if infinite number of roots
@note Calculation precision is considered to be DBL_EPSILON.
************************************************************************************/
Здесь важны 2 (две (не одна (1, одна (одна)), а две (2, две (две (не одна (ну вы поняли)))) звездочки в начале коммента. По ним доксиген распознает документирующий коммент.
Более обширное wiki, но на английском, смотри здесь: http://www.rtems.org/wiki/index.php/Doxygen_Recommendations А также множество примеров и дельных рекомендаций.
Вот пример доксигеновской документации: http://storage.ded32.net.ru/Lib/TX/TXUpdate/Doc/HTML.ru Она понятна даже семиклассникам! :)
Вот ее исходник: http://sourceforge.net/projects/txlib/files/TXLib/TXLib.h/download
К примеру, такой код:
//{=================================================================================
//! @file square_equation.c
//! @date 2013-09-26
//! @author Sergey Ivanychev <[email protected]>, 376 group, DCAM MIPT
//! @version 1.03
//! @note V1.01:
//! - added function squaresolve()
//! - main() has been changed
//! - added multiple equations support
//! - calculates and returns the sum of the roots
//!
//! @note V.1.02:
//! - added "square_eq" structure where factors and number of roots are contained //!
//! - fixed squaresolve():
//! -- there's no -0.0 anymore!
//! - fixed main():
//! -- the roots aren't stored in memory anymore
//! - added check if number of equations is positive
//! - removed the array of roots, structure square_eq is created
//! @par V.1.03
//! - added preprocessor support
//! -- from now, float numbers are compared using IS_ZERO, IS_ABOVE_ZERO, IS_BELOW_ZERO
//! -- my ASSERT added, if #define DEBUG is commented out, ASSERT would be replaced with space
//! -- added #define OUT, which cancels friendly output if #define _EJC (Judge System Support)
//! - doxygen comments added
//!
//! @note TODO: - Figure out how to use the dynamic memory
//}==============================================================================================
//----------------------------------------------------------------------------------------
#include <stdio.h>
#include <math.h>
#include <float.h>
#define IS_ZERO(x) (fabs(x) < DBL_EPSILON)
#define IS_ABOVE_ZERO(x) (x > DBL_EPSILON)
#define IS_BELOW_ZERO(x) (x < -DBL_EPSILON)
//--------------------------------------------------------------------------
//#define _EJC
//--------------------------------------------------------------------------
#ifdef _EJC
#define OUT if(0)
#else
#define OUT
#endif // _EJC
//--------------------------------------------------------------------------
#define DEBUG
//--------------------------------------------------------------------------
#ifdef DEBUG
#define ASSERT(cond) \
if (!(cond)) {\
printf("All gone bad: %s, file: %s, line: %d\n", #cond, __FILE__, __LINE__);\
abort();\
}
#else
#define ASSERT(cond)
#endif //DEBUG
...
Даст вот такой красивый док:
Язык комментов - русский или английский? Я думаю, на 1 курсе надо разрешать и то, и то, но откровенно способствовать тем, кто пишет по-английски (без явного гугл-транслейта, легко распознаваемого по ужасной грамматике). Например, ревьювить их код в первую очередь.
Предлагаю при выводе информации о программе (название, автор, версия и т.п.), приглашений для ввода и пояснений ответов начинать строчку со знака, скажем, # (решетка). И не перемешивать ввод-вывод данных задачи с пояснениями. Т.е. вместо
Уравнение имеет 2 различных корня: x1 = -3 и x2 = +3
Уравнение не имеет корней
выводить так:
# Уравнение имеет различных корней:
2
# Их значения:
-3 +3
0
# Уравнение не имеет корней
Это позволит при разработке интеловской тестирующей системы пропускать строчки с пояснениями и избегать известной проблемы, когда тестирующий сервер выдает ошибку представления данных, принимая пояснения за ответ.
Строчки с отладочными данными, не входящими в ответ, тоже можно помечать так же, и они будут также пропущены.
ded
Press RESET to continue...