Здравствуйте, minorlogic, Вы писали:
M>Лучше приведите пример , а мы бы попробовали код причесать ?
хорошо известный в узком кругу пример: исходники рахличных алгоритмов сжатия. есть исходники zip и в этом алгоритме моджет разобраться любой желающий. есть исходники множества других алгоритмов без комментариев и как они работают — понять невозможно
попробуйте взять исходники моих алгоритмов http://www.haskell.org/bz/dict.zip или http://www.haskell.org/bz/rep.zip, удалите оттуда комментарии и попробйуте хоть что-нибудь понять. затем попробуйте остановиться на полпути и разобраться в рабте функций, имея в распорядении только внешние по отношению к функциям комментарии. уверен, что это не получится. нужно комментировать каждый блок кода — это максимально упрощает понимание кода, в том числе и самому автору спустя небольшое время
Это пример не показательный. Тут сложности алгоритмические .
Если человек понимает как работает алгоритм то и код для него будет понятен. И совершенно необязательно коментировать сам код , просто описать алгоритм.
Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.
M>Если человек понимает как работает алгоритм то и код для него будет понятен. И совершенно необязательно коментировать сам код, просто описать алгоритм.
надо сначала детально описать сам алгоритм, а потом детально прокомментировать его реализацию. потому что во-первых, это просто разные вещи, во-вторых никому не нужно сидеть и догадываться, какой кусок кода к какой части алгоритма относится
и вообще непонятно, к чему относилось твоё обещание переписать код. вот он пожалуйста — переписывай. или ты полагал, что люди детально комментируют тривиальные алгоритмы?
M>Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.
Здравствуйте, minorlogic, Вы писали:
M>Лучше приведите пример , а мы бы попробовали код причесать ?
вот ещё. уж тут никаких алгоритмов
// Конструирует объект типа GRZIP_METHOD с заданными параметрами упаковки
// или возвращает NULL, если это другой метод сжатия или допущена ошибка при задании параметров
COMPRESSION_METHOD* parse_GRZIP (char** parameters)
{
if (strcmp (parameters[0], "grzip") == 0) {
// Если название метода (нулевой параметр) - "grzip", то разберём остальные параметры
GRZIP_METHOD *p = new GRZIP_METHOD;
int error = 0; // Признак того, что при разборе параметров произошла ошибкаwhile (!error && *++parameters) // Переберём все параметры метода
{
char *param = *parameters;
if (strlen(param)==1) switch (*param) { // Однобуквенные параметрыcase's': p->AlternativeBWTSort = 1; continue;
case'a': p->AdaptiveBlockSize = 1; continue;
case'l': p->EnableLZP = 0; continue;
case'd': p->DeltaFilter = 1; continue;
case'p': p->AdaptiveBlockSize=0; p->EnableLZP=0; p->DeltaFilter=1; continue;
}
else switch (*param) { // Параметры, содержащие значенияcase'm': p->Method = parseInt (param+1, &error); continue;
case'b': p->BlockSize = parseMem (param+1, &error); continue;
case'l': p->MinMatchLen = parseInt (param+1, &error); continue;
case'h': p->HashSizeLog = parseInt (param+1, &error); continue;
}
// Сюда мы попадаем, если в параметре не указано его название
// Если этот параметр удастся разобрать как целое число (т.е. в нём - только цифры),
// то присвоим его значение полю MinMatchLen, иначе попробуем разобрать его как BlockSizeint n = parseInt (param, &error);
if (!error) p->MinMatchLen = n;
else error=0, p->BlockSize = parseMem (param, &error);
}
if (error) {delete p; return NULL;} // Ошибка при парсинге параметров методаreturn p;
} else
return NULL; // Это не метод grzip
}
Здравствуйте, BulatZiganshin, Вы писали:
BZ>и вообще непонятно, к чему относилось твоё обещание переписать код. вот он пожалуйста — переписывай. или ты полагал, что люди детально комментируют тривиальные алгоритмы?
Конечно мои высказывания были к людям коментирующим гетеры и сетеры, не говоря уж о тривиальных алгоритмах. Изначально можно посмотреть стиль предложенный автором топика.
M>>Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.
BZ>и ты в этом коде разобрался?
Если подхидить к написанию кода более серьезно толучше использовать фреймворк для парсинга command line. В данном случае наблюдается скорее собранный на коленке код на который отводилось немного времени.
Переписывать этот код без изменения функциональности я бы не стал. Он достаточно тривиален и не должен вызывать никаких затруднений при чтении.
BZ>// Конструирует объект типа GRZIP_METHOD с заданными параметрами упаковки
BZ>// или возвращает NULL, если это другой метод сжатия или допущена ошибка при задании параметров
Полезный коментарий описывающий поведение функции.
BZ>COMPRESSION_METHOD* parse_GRZIP (char** parameters)
BZ>{
BZ> if (strcmp (parameters[0], "grzip") == 0) {
BZ> // Если название метода (нулевой параметр) - "grzip", то разберём остальные параметры
не очень полезный. я бы предложил так
if (strcmp (parameters[0], "grzip") != 0)
{
return NULL; // required signature "grzip" not found:
}
BZ> GRZIP_METHOD *p = new GRZIP_METHOD;
p - название переменной немного урезано.
BZ> int error = 0; // Признак того, что при разборе параметров произошла ошибкаint errorCount = 0; коментарий тут лишний по мне.
BZ> while (!error && *++parameters) // Переберём все параметры метода
лишний коментарий, очевидно из контекста
BZ> {
BZ> char *param = *parameters;
BZ> if (strlen(param)==1) switch (*param) { // Однобуквенные параметры
BZ> case's': p->AlternativeBWTSort = 1; continue;
BZ> case'a': p->AdaptiveBlockSize = 1; continue;
BZ> case'l': p->EnableLZP = 0; continue;
BZ> case'd': p->DeltaFilter = 1; continue;
BZ> case'p': p->AdaptiveBlockSize=0; p->EnableLZP=0; p->DeltaFilter=1; continue;
BZ> }
BZ> else switch (*param) { // Параметры, содержащие значения
BZ> case'm': p->Method = parseInt (param+1, &error); continue;
BZ> case'b': p->BlockSize = parseMem (param+1, &error); continue;
BZ> case'l': p->MinMatchLen = parseInt (param+1, &error); continue;
BZ> case'h': p->HashSizeLog = parseInt (param+1, &error); continue;
BZ> }
Информация о формате параметров лучше бы лежала дет в одном месте , просто упоминание что есть однобуквенные с такими свойствами или многобуквенные с другими.
далее коментарий полезен тем что объясняет ожидаемое поведение парсера.
BZ> // Сюда мы попадаем, если в параметре не указано его название
BZ> // Если этот параметр удастся разобрать как целое число (т.е. в нём - только цифры),
BZ> // то присвоим его значение полю MinMatchLen, иначе попробуем разобрать его как BlockSize
BZ> int n = parseInt (param, &error);
BZ> if (!error) p->MinMatchLen = n;
BZ> else error=0, p->BlockSize = parseMem (param, &error);
BZ> }
BZ> if (error) {delete p; return NULL;} // Ошибка при парсинге параметров метода
довольно мусорный коментарий как по мне
BZ> return p;
BZ> } else
тоже мусорный.
BZ> return NULL; // Это не метод grzip
BZ>}
BZ>
Хочу обратить внимание что нет обработки ошибок, что в свою очередь порождает большие проблемы с использованием консольного приложения.
Здравствуйте, BulatZiganshin, Вы писали:
BZ>// Конструирует объект типа GRZIP_METHOD с заданными параметрами упаковки
Нельзяли эту информацию выразить типом возвращаемого значения и именем функции?
BZ> // Если название метода (нулевой параметр) — "grzip", то разберём остальные параметры
можно ли кодом выразить, что нулевой параметр — это название метода?
можно ли "разберем остальные параметры" тоже выразить кодом типа разберем(остальные_параметры)
а еcли бы использовался не C а другой язык?
P.S. иногда я пишу псевдокод на питоне а потом транслирю в то дерьмо на котором работаю...
Здравствуйте, VladD2, Вы писали:
VD>Здравствуйте, A.A.L., Вы писали: AAL>>3. перед определением членов класса/деклараций функций и т.д. AAL>>В общем то, что потом скармливается в DoxyGen AAL>>Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.
AAL>>Помедоры не кидать !
фишка в том, что я с AAL полностью согласен — хороший дизайн как правило оставляет необходимость комментировать классы и их члены, не залезая внутрь. Как и из любого правила, из этого есть исключения по поводу которых стоит общаться отдельно.
VD>Ну, что же небольшой тестик. Вот тебе код без коментариев (примитивный). Объясни, что он делает? VD>
VD>int A(int m, int n)
VD>{
VD> if (m == 0) return n + 1
VD> else if (n == 0) return A(m - 1, 1)
VD> else return A(m - 1, A(m, (n - 1)))
VD>}
VD>
VD>Просьба никому постороннему не помогать.
из имени метода или комментария к нему ясно что он делает (не "как", но "что"). Так что у тебя этот метод делает "А". Именно "А", а не "функцию старика такого-то", иначе метод бы так и назывался AckermannFunction! Что такое "А" должно быть общеизвестно в твоей предметной области, либо прописано в постановке задачи, но в последнем случае ссылка на это описание должна быть в комментарии к методу.
(обсуждение старое, так что думаю кому надо, тот разобрался что за алгоритм)
OZ>Комментарий к методу/функции должен быть в творительном падеже — ибо метод/функция обычно не "вещь в себе", а по принципам ООП определенное результативное действие. Соответственно и комментарий должен описывать её в виде волеизьявления: "Нарисовать дугу на битмапе".
Причем тут падежи, когда речь о _глаголе_? Правильно твоя мысль выражается — "в инфинитиве".
Хотя у меня все комменты в 3ем лице — draws, creates и так далее.
Код нормальный, только одно замечание — я бы никогда не оставлял пустых строк внутри функции. Очень удобно, когда пустые строки только _между_ сущностями, а не внутри них.