Написал и забыл ? Комментируй свой код!

[BiZaJe]

ЗАЧЕМ НАМ НУЖНЫ КОММЕНТАРИИ?​

Комментарий к коду - это одна из важнейших составляющих программирования. "Зачем нам нужны комментарии? Ведь их никто не читает..." Практический так думает каждый новичок. Но почему они так важны в исходном коде? Хорошо написанный комментарий, даст огромное преимущество вам, но и также другим программистам которые будут смотреть ваш исходный код.
Что же дает хорошо написанный комментарий?

• Краткое описание кода - Краткий комментарий избавит вас или других программистов от нужды смотреть ту или иную часть кода и разбираться в нем.​
• Просмотр кода через какое-то время - А вдруг будете писать длинный код в 10 000 строк и вам понадобиться какая-та часть кода? Тут и выручит комментарий. Вам не придется сидеть и вспомнить, что делает та или иная строчка кода.​
• Избавление от нужды удаления не нужного - Приходит время когда нужно, что-то проверить, но не охота лишний раз удалять/копировать/вставлять код заново. Тут нам и поможет за комментирование кода.​

ВИДЫ КОММЕНТАРИЕВ​

В программирование выделяет два вида комментариев:

• Одно строчный комментарий - выглядит он так​

// Краткое и красивое описание кода

• Много строчный комментарий​

/*
    А может попробуем вот так?
*/

И ТАКЖЕ ЗАПОМНИТЕ ЭТО ПРАВИЛО. ОНО МОЖЕТ ПРИВЕСТИ К ПЛОХИМ ПОСЛЕДСТВИЯМ.

/*
    // НИКОГДА НЕ ДЕЛАЕТЕ ВЛОЖЕННЫЕ КОММЕНТАРИИ.
    // ЭТО ПРИВЕДЕТ К ОШИБКАМ В КОДЕ!!!
    // КАК ЭТО ДЕЛАЮ Я СЕЙЧАС ВАМ НА ДЕМОНСТРАЦИЮ!
*/

Также надо подчеркнуть тот момент, что при вложенном одно строчном комментарии в много строчный ошибок не выявится, но со стороны оформления - это не правильно, а при вложенном много строчном /* */ ошибка сразу проявит себя.

ШЕФ, А КАК ДЕЛАТЬ ХОРОШИЙ КОММЕНТАРИЙ?​

• Хорошо описывающий комментарий - это плохо!

Пиши комментарии кратко и ясно! Проанализируйте свой код, сделаете небольшой вывод, что и как работает, каков поток работы вашего кода при различных ситуациях. Тогда у вас получится хорошее и краткое описание кода.
* При желании можете ознакомится с UML - который разъясняет архитектуру кода.

• Комментируйте каждую сложную строку кода или длинную его часть.

// Напримере возьмем древний код по стрипу оружия у игрока

/**
    * Отбирает оружие у игрока по WEAPON_ID
    *
    * @param id - Индекс игрока
    * @param weapon - Индекс оружия (Example: weapon_ak47)
    * @return - Возращает 1 если оружие отобрано
**/

stock ham_strip_weapon(id,weapon[])
{
     if(!equal(weapon,"weapon_",7)) return 0

    new wId = get_weaponid(weapon)
    if(!wId) return 0

    new wEnt
    while((wEnt = engfunc(EngFunc_FindEntityByString,wEnt,"classname",weapon)) && pev(wEnt,pev_owner) != id) {}
    if(!wEnt) return 0

    if(get_user_weapon(id) == wId) ExecuteHamB(Ham_Weapon_RetireWeapon,wEnt)

    if(!ExecuteHamB(Ham_RemovePlayerItem,id,wEnt)) return 0
    ExecuteHamB(Ham_Item_Kill,wEnt);

    set_pev(id,pev_weapons,pev(id,pev_weapons) & ~(1<<wId))
 
    return 1
}

• Комментируйте если в коде есть какие-то тонкости или невиданные вещи.

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

* ЕСЛИ ЧАСТЬ КОДА, ЧТО-ТО УСЛОЖНЯЕТ СТАРАЙТЕСЬ ВЫНЕСТИ ЭТО В ОТДЕЛЬНУЮ ФУНКЦИЮ

Также готов услышать мнение более квалифицированных программистов по этой теме.

​

 

[irrumabo_me_nomen]

Их для навигациии и стркурирования ещё использовать удобно. Особенно когда код размером с "Войну и мир".

 

[Minni]

А что будет-то?)

/*
    // НИКОГДА НЕ ДЕЛАЕТЕ ВЛОЖЕННЫЕ КОММЕНТАРИИ.
    // ЭТО ПРИВЕДЕТ К ОШИБКАМ В КОДЕ!!!
    // КАК ЭТО ДЕЛАЮ Я СЕЙЧАС ВАМ НА ДЕМОНСТРАЦИЮ!
/*

7 Сен 2020

Если сделать кривой многострочный комментарий, как ты, то будет ошибка. Это и так очевидно. Пример вложенных комментариев)

 

[fantom]

Redundant comments are just places to collect lies and misinformation

Дядя боб(с)

 

[BiZaJe]

Minni, Забыл подчеркнуть, что при // Ошибок не возникает, но все равно это не правильно, а при /* */ вылетит ошибка мгновенно.

 

[RockTheStreet]

BiZaJe, Почувствуй разницу.

 

[Ayk]

BiZaJe, в Павне, однострочный спокойно входит в многострочный, а вот один многострочный в другой многострочный ставить нельзя, ибо:

/*
  /*
  */  <- компилятор засчитает как конец внешнего блока
*/  <- вызывает ошибку

 

[BiZaJe]

melfyk, Разницу в чем?
Ayk, подчеркнул этот момент

 

[RockTheStreet]

Разницу в чем?

Вот именно, разницы нет. Ни разницы, ни ошибок.

 

[BiZaJe]

melfyk, Ладно, тут на другом уровне разговор идёт.
Чтоб понять разницу нужно лезть глубже (Документация/Оформление кода и т.д)