Re[2]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 01.08.07 16:22
Оценка:
Лучше приведите пример , а мы бы попробовали код причесать ?
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[3]: Стиль комментариев в коде
От: BulatZiganshin  
Дата: 01.08.07 16:56
Оценка:
Здравствуйте, minorlogic, Вы писали:

M>Лучше приведите пример , а мы бы попробовали код причесать ?


хорошо известный в узком кругу пример: исходники рахличных алгоритмов сжатия. есть исходники zip и в этом алгоритме моджет разобраться любой желающий. есть исходники множества других алгоритмов без комментариев и как они работают — понять невозможно

попробуйте взять исходники моих алгоритмов http://www.haskell.org/bz/dict.zip или http://www.haskell.org/bz/rep.zip, удалите оттуда комментарии и попробйуте хоть что-нибудь понять. затем попробуйте остановиться на полпути и разобраться в рабте функций, имея в распорядении только внешние по отношению к функциям комментарии. уверен, что это не получится. нужно комментировать каждый блок кода — это максимально упрощает понимание кода, в том числе и самому автору спустя небольшое время
Люди, я люблю вас! Будьте бдительны!!!
Re[4]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 01.08.07 18:39
Оценка:
Это пример не показательный. Тут сложности алгоритмические .

Если человек понимает как работает алгоритм то и код для него будет понятен. И совершенно необязательно коментировать сам код , просто описать алгоритм.

Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[5]: Стиль комментариев в коде
От: BulatZiganshin  
Дата: 01.08.07 19:59
Оценка:
M>Если человек понимает как работает алгоритм то и код для него будет понятен. И совершенно необязательно коментировать сам код, просто описать алгоритм.

надо сначала детально описать сам алгоритм, а потом детально прокомментировать его реализацию. потому что во-первых, это просто разные вещи, во-вторых никому не нужно сидеть и догадываться, какой кусок кода к какой части алгоритма относится

и вообще непонятно, к чему относилось твоё обещание переписать код. вот он пожалуйста — переписывай. или ты полагал, что люди детально комментируют тривиальные алгоритмы?

M>Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.


и ты в этом коде разобрался?
Люди, я люблю вас! Будьте бдительны!!!
Re[3]: Стиль комментариев в коде
От: BulatZiganshin  
Дата: 01.08.07 20:27
Оценка:
Здравствуйте, 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, иначе попробуем разобрать его как BlockSize
      int 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
}
Люди, я люблю вас! Будьте бдительны!!!
Re[6]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 02.08.07 03:59
Оценка:
Здравствуйте, BulatZiganshin, Вы писали:

BZ>и вообще непонятно, к чему относилось твоё обещание переписать код. вот он пожалуйста — переписывай. или ты полагал, что люди детально комментируют тривиальные алгоритмы?


Конечно мои высказывания были к людям коментирующим гетеры и сетеры, не говоря уж о тривиальных алгоритмах. Изначально можно посмотреть стиль предложенный автором топика.

M>>Как контрпример я могу предложить MPEG реализации где сам алгоритм описан отдельно а в коде почти что нет коментариев.


BZ>и ты в этом коде разобрался?


Конечно разобрался.
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[4]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 02.08.07 05:46
Оценка:
В приведенном участке кода я не вижу злоупотребления коментариями , я бы парочку снес. Например error -> errorCount и можно не коментировать .
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[4]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 02.08.07 05:46
Оценка:
Если подхидить к написанию кода более серьезно толучше использовать фреймворк для парсинга command line. В данном случае наблюдается скорее собранный на коленке код на который отводилось немного времени.

Переписывать этот код без изменения функциональности я бы не стал. Он достаточно тривиален и не должен вызывать никаких затруднений при чтении.
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[4]: Стиль комментариев в коде
От: minorlogic Украина  
Дата: 02.08.07 05:59
Оценка:
Здравствуйте, BulatZiganshin, Вы писали:

BZ>
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>


Хочу обратить внимание что нет обработки ошибок, что в свою очередь порождает большие проблемы с использованием консольного приложения.
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re[4]: Стиль комментариев в коде
От: no4  
Дата: 02.08.07 11:20
Оценка:
Здравствуйте, BulatZiganshin, Вы писали:

BZ>// Конструирует объект типа GRZIP_METHOD с заданными параметрами упаковки


Нельзяли эту информацию выразить типом возвращаемого значения и именем функции?

BZ> // Если название метода (нулевой параметр) — "grzip", то разберём остальные параметры


можно ли кодом выразить, что нулевой параметр — это название метода?

можно ли "разберем остальные параметры" тоже выразить кодом типа разберем(остальные_параметры)

а еcли бы использовался не C а другой язык?

P.S. иногда я пишу псевдокод на питоне а потом транслирю в то дерьмо на котором работаю...
... << RSDN@Home 1.1.4 stable SR1 rev. 568>>
Re[3]: Стиль комментариев в коде
От: deekey  
Дата: 16.08.07 18:38
Оценка:
Здравствуйте, 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! Что такое "А" должно быть общеизвестно в твоей предметной области, либо прописано в постановке задачи, но в последнем случае ссылка на это описание должна быть в комментарии к методу.

(обсуждение старое, так что думаю кому надо, тот разобрался что за алгоритм)
Re: Стиль комментариев в коде
От: Maxim S. Shatskih Россия  
Дата: 16.08.07 19:03
Оценка:
OZ>Комментарий к методу/функции должен быть в творительном падеже — ибо метод/функция обычно не "вещь в себе", а по принципам ООП определенное результативное действие. Соответственно и комментарий должен описывать её в виде волеизьявления: "Нарисовать дугу на битмапе".

Причем тут падежи, когда речь о _глаголе_? Правильно твоя мысль выражается — "в инфинитиве".

Хотя у меня все комменты в 3ем лице — draws, creates и так далее.

Код нормальный, только одно замечание — я бы никогда не оставлял пустых строк внутри функции. Очень удобно, когда пустые строки только _между_ сущностями, а не внутри них.
Занимайтесь LoveCraftом, а не WarCraftом!
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.