Комментирование кода

Serab

Вот бля, ну скажите же, что комментарии «примерно раз в три строчки» как самоцель — это пиздец! Я бы наоборот относился с подозрением к чувакам, которые не могут писать понятный код, не требующий объяснения каждого действия? Или ч0ваще?

Maurog

мы все за тебя!
тебя отпустило?

doublemother

А тут вопрос в том, что называть «понятный код», и кто будет устанавливать такой критерий. Я, например, встречал кучу людей, которые сообщают, что пишут понятный «самодокументируемый код», поэтому и комментарии писать не нужно. Конечно, кому-то это удаётся, но в большинстве случаев у таких писателей выходит лютое нечто.
Поэтому лучше к этому подходить с той позиции, что если комментарии есть, то при необходимости их всегда можно вырезать парой регулярок. А если их нет, а код непонятный, то жопа.

geja_03

Код на С++ понятен без комментариев (с) не помню кто

val63

Вот так чоле?:)



for (

    //в этой строке я объявляю переменную i типа int и присваиваю ей значение 0

    int i = 0;

    //если значение переменной i будет больше или равно количеству элементов в списке,

    //цикл остановится

    i < list.Count;

    //каждую итерацию цикла увеличиваем значение переменной i на один

    i++;)

hwh2010

видел такое

$moscowAndPiter = array(Config::getInstance->moscow_region_geo_id => "Московская область", "60617951866" => "Ленинградская область"); // IZ: no comments

при этом сцуко там тыщу раз есть что комментировать (например, вроде как имелись в виду не МО и ЛО, а М+МО и СПБ+ЛО соотв.)
короче такие комменты лучше не писать, они тока бесят

ava3443

недавно пришлось копаться в неподдерживаемом коде, порадовали комменты в одном из методов:

//@@ !State can be changed in enother thread

// must be guarded from here

и затем 50 строчками ниже:

//@@ To here

соответственно, это "must be" отражено лишь в комментариях, но не в коде

P.S. автора комментов ещё в 2007 году уволили за профнепригодность

AE169

Вот такого коментатора я вживую видел. Даже работал рядом.

VitMix

for ( 

//в этой строке я объявляю переменную i типа int и присваиваю ей значение 0 

int i = 0; 

//если значение переменной i будет больше или равно количеству элементов в списке, 

//цикл остановится i < list.Count; 

//каждую итерацию цикла увеличиваем значение переменной i на один 

i++;)

О! Можно бота написать, который будет автоматически вставлять подобные комментарии. Очень поможет тем, кому надо в коде разобраться, но кто не знает языка.

Serab



int MegaFunc    

{                  

    X a;     // This var gets destroyed _____

    Some;  //                              \  

    Cool;  //                               |r

    Stuff; //                               |i

    Etc;   //                               |g

    Etc2;  //                               |h

             //     h e r e                   |t

    return 0;//  <___________________________/

}

YUAL

О! Можно бота написать, который будет автоматически вставлять подобные комментарии. Очень поможет тем, кому надо в коде разобраться, но кто не знает языка.

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

bleyman

Steve Yegge писал что это типа такой признак неопытного программиста. Как пятилетний ребёнок постоянно рассказывает сам себе про то, что он делал, что собирается делать, и что делал раньше, так вот и неопытному программисту который пока не умеет думать прямо кодом, нужен нарратив.
http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm...

val63

неопытному программисту который пока не умеет думать прямо кодом, нужен нарратив.

Таких еще системными архитекторами зовут :-)

Serab



int MegaFunc    

{                  

    X a;     // This var gets destroyed _____

    Some;  //  П А Р И К М А                \  

    Cool;  //        Х                      |r

    Stuff; //      Е   С                    |i

    Etc;   //    Р   К                      |g

    Etc2;  //      А   Я                    |h

             //     h e r e                   |t

    return 0;//  <___________________________/

}

Anturag



// 

// Dear maintainer:

// 

// Once you are done trying to 'optimize' this routine,

// and have realized what a terrible mistake that was,

// please increment the following counter as a warning

// to the next guy:

// 

// total_hours_wasted_here = 39

//

snega25

for (

    //в этой строке я объявляю переменную i типа int и присваиваю ей значение 0

    int i = 0;

    //если значение переменной i будет больше или равно количеству элементов в списке,

    //цикл остановится

    i < list.Count;

    //каждую итерацию цикла увеличиваем значение переменной i на один

    i++;)

ТС жаловался на «примерно раз в три строчки», а не три строчки комментов на одну строчку кода.
Этож п..дец в квадрате получается.

Commandor

Коллега таким увлекается.

def authernticate(func):

  def decorated(self, request, *args, **kwargs):

    

    # Get user and additional cookies

    user, cookies = get_current_user(request)

    

    # Check user

    if not user:

      return HttpResponseRedirect(self.get_full_url(settings.LOGIN_URL

      

    # Remember user in the request object

    request.current_user = user

    

    # Call a view

    response = func(self, request, *args, **kwargs)

    

    # Set additional cookies

    for cookie in cookies:

      response['Set-Cookie'] = cookie

      

    # Return the result

    return response

    

  return decorated

Он еще и юнит-тесты писать умеет

Оставить комментарий