Идеальные комментарии в программе

@Mikhaylo · Регистрация: 20.09.2014

Author24 — интернет-сервис помощи студентам

Интересуюсь технологиями и техниками в программировании. Один из вопросов интересных - какие правила для написания хороших комментариев в программе.
Есть правила для новичков - вроде "не пиши, что делает программа дословно", ну и правило, что хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе.

Последнее утверждение, конечно, ложь, так как человек, изучающий программу, может быть не в курсе предметной области. Например, может быть комментарий "А принтер этой модели не умеет печатать букву Ё!".

Я уже в соседней теме писал, что меня интересует IDE/ЯП для программиста, а не для компилятора/процессора. В существующих языках комментарий - это простая строка с любой ахинеей, которая предназначена для программиста, но не для компилятора. И в определенный момент я понял, что в моей IDE комментариев не будет в том виде, как в существующих языках. В моей IDE (которой ещё почти нет) комментарии заменят неким образом структурированные комментарии. Моя цель - понять, как структурировать. Ну и главный вопрос - как понять, что комментарии завершены, достаточны и понятны?

Рыжий Лис · 21.11.2020, 11:18

Сообщение от Mikhaylo

В моей IDE

Непонятно при чём здесь IDE и код.

Сообщение от Mikhaylo

Моя цель - понять, как структурировать.

Ну возьми следующие примеры:

Lua

--- Геометрическая сумма
---@param x number
---@param y number
---@return number
function math.sum_geometry(x, y)
    return math.sqrt(math.pow(x, 2) + math.pow(y, 2))
end

Python

def validate_passport_serial_or_number(serial_or_number):
    """
    Валидация серии или номера паспорта
 
    >>> validate_passport_serial_or_number('2001860001')
    '20 01 860001'
    >>> validate_passport_serial_or_number('2001')
    '20 01'
 
    :param serial_or_number: серия номера или…
    :type serial_or_number str
    :rtype str
    """
    pass

C#

/// обёртка для ошибок
///
/// ```rust
/// #[get("/")]
/// pub fn index() -> Result<String, ViewError> {
///     let _ = var?;  // любая ошибка, которая может быть приведена к ViewError
///     Ok(String::from("all ok"))
/// }
/// ```
#[derive(Debug)]
pub enum ViewError {
    OracleError(OracleError)
}

@Mikhaylo · 21.11.2020, 12:34 **[ТС]**

Сообщение от Рыжий Лис

Непонятно при чём здесь IDE и код.

Все просто: IDE может помогать составлять хорошие комментарии.
Мы привыкли, что комментарии - это просто набор произвольных букв. В этой теме предлагаю отвыкнуть.)
Одна из простых идей - привязка комментария к любому элементу языка программирования. Мы помещаем комментарий сверху, снизу или справа от инструкции, точнее, строки с инструкцией или ее частью. Но не можем как-то удобно расположить комментарий, например, внутри вызова функции:

Код

function1(0, a);

Хотелось бы прокомментировать, почему первый аргумент 0. Навел на аргумент курсором, а там комментарий всплыл...

Рыжий Лис · 21.11.2020, 12:44

Сообщение от Mikhaylo

Хотелось бы прокомментировать, почему первый аргумент 0.

Давно всё решено.

C

1	function1(0 /* количество кошек /, a / количество еды в килограммах */);

Python

def function1(count_cats: int, food: int):
    """
    документация к функции
 
    :param count_cats: количество кошек
    :param food: количество еды в килограммах
    """
    pass
 
function1(count_cats=0, food=a)

Рыжий Лис · 21.11.2020, 12:52

Уже давно изобретено до вас

@Mikhaylo · 21.11.2020, 12:56 **[ТС]**

Ох уж это приверженство plain-text programming language!)))
Это мое определение для всех ЯП, к которым мы привыкли.

Я намеренно стираю грань между IDE и ЯП, так как понимаю, что способы вывода и ввода информации - это тоже часть языка [программирования] и тоже подлежат стандартизации (как части языка).

Добавлено через 1 минуту
А вот картинка уже интереснее!

@vantfiles · 22.11.2020, 00:11

Есть к примеру Doxygen

https://www.doxygen.nl/index.html

@Mikhaylo · 22.11.2020, 09:01 **[ТС]**

Я открыл пример доксигеновской документации http://dtris.sourceforge.net/d... index.html

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

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

Теперь я хочу сформулировать принципы идеального комментирования:
1. Работу программы комментировать не надо, лучше применяй хорошие абстракции.
2. Прокомментируй окружение программы, информация о внешних системах не содержится в коде.
3. Неподготовленный программист способен самостоятельно проанализировать код и может что-то знать про окружение (просто побывав в этом самом окружении в качестве тестировщика). Однако, возможны ситуации, когда код действительно сложный, а окружение полноценно изучить, побывав в нем, затруднительно.

Добавлено через 13 минут
4. Комментатор сам может не знать окружение, плохо разбираться в своей программе или не уделять достаточного внимания комментированию. На уровне IDE эта проблема должна и может быть решена. Для этого IDE должна контролировать соблюдение принципов комментирования, я уж не говорю, что помогать с абстракциями в коде.

Рыжий Лис · 22.11.2020, 09:27

Сообщение от Mikhaylo

3. Неподготовленный программист способен самостоятельно проанализировать код

Ха-ха, вот делать мне нечего, как читать чужой код. Вообще все эти абстракции как раз прячут детали реализации, наружу выставляя только интерфейс. И вот как раз его нужно задокументировать (прокомментировать) - описать аргументы функции/методы класса - привести примеры использования и покрыть тестами.

Если я прочитал описание документации и ничего не понял, то пойду искать примеры в этой же документации. В более худших случаях - ковырять тесты и копировать код оттуда. Если же ничего нет - то только тогда придётся вскрыть "чёрный ящик" и читать сам код.

C#

    /// Create a new `Rocket` application using the configuration information in
    /// `Rocket.toml`. If the file does not exist or if there is an I/O error
    /// reading the file, the defaults are used. See the [`config`]
    /// documentation for more information on defaults.
    ///
    /// This method is typically called through the
    /// [`rocket::ignite()`](::ignite) alias.
    ///
    /// # Panics
    ///
    /// If there is an error parsing the `Rocket.toml` file, this functions
    /// prints a nice error message and then exits the process.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # {
    /// rocket::ignite()
    /// # };
    /// ```
    #[inline]
    pub fn ignite() -> Rocket {
        // Note: init() will exit the process under config errors.
        Rocket::configured(config::init())
    }

C#

#[cfg(test)]
mod test {
    use reqwest::blocking::Client;
    use reqwest::StatusCode;
 
    #[test]
    fn http_user_agent() {
        let client = Client::new();
        let res = client.get("http://httpbin.org/user-agent").send().unwrap();
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(res.text().unwrap(), "{\n  \"user-agent\": null\n}\n");
    }
}

@Mikhaylo · 22.11.2020, 10:27 **[ТС]**

Это вы про тот случай, когда алгоритм действительно сложный для понимания. А неподготовленный программист всё-таки может.

Добавлю ещё один принцип:
5. Программа является отражением (зеркалом) окружения. Но, как правило, неточным отражением. Это означает, что, описывая окружение, становится отчасти понятно, как должна работать (как работает) программа.

Этот принцип восходит к принципу необходимого разнообразия систем Эшби. Но надо учитывать, что разнообразие не всегда необходимое.)))

С 5-ым принципом гораздо интереснее. Попробую продемонстрировать на примере:

Кликните здесь для просмотра всего текста

В этой схеме все связи равнозначны, хотя фактически можно выделить основные связи, а часть обозначить как вспомогательные, дополнительные, связи "на всякий случай" и прочие категории.

Берём и расставляем для всех связей веса-комментарии (компилятор не берет в расчет эти веса). Основные связи пожирнее отобразить, вспомогательные потоньше. Это комментирование кода непосредственно.
Можно также описать через внешнее окружение: написать, что для игрока в 3Д-Тетрис важны изображение стакана, фигурок (игровая сцена) и кнопки управления. Всякие там окна Start и окна Gameover/Congratulation менее важны, подсчет игровых очков тоже не суть. Это тоже расставит веса объектам, функциям, переменным, связям.
Этой информации нет ни в коде, и основная проблема - программисты не знают, что это важно для понимания.

Самое правильное описание окружения программы - это математическая модель окружения. Однако это дорого, сложно и не совсем необходимо, так как программа является инверсным отражением окружения (почти). Если есть код программы, то необходимость в матмодели окружении частично отпадает. Следует добавить немного той информации, которой не видно в "зеркале".
Сложно понять, всю эту околофилософскую чушь про "зеркало", "необходимое разнообразие" и т.д.
Чтобы справиться с этой сложностью, я для себя принял, что часто важной информацией об окружении является распределение частот (вероятностей) входных переменных. Например, у пульта телевизора 40 кнопок, и распределение частот нажатий на кнопки смещено к тому используются в основном пять кнопок: Power, Vol+, Vol-, Ch+, Ch-. Эта информация помогает выделить главные функции в ПО телевизора. Компилятору эта информация не нужна, в коде эта информация не содержится.

@Mikhaylo · 22.11.2020, 10:34 **[ТС]**

Рыжий Лис, сейчас доберёмся до ваших кусков программ. Вы правильно подметили, что абстракции скрывают детали реализации. Тогда решение такое: то, что скрыто под абстракцией, считать внешним окружением, и тогда все встаёт на свои места. При чем забавно, что это окружение имеет модель в виде кода, который можно подглядеть (не всегда).

@Shamil1 · 23.11.2020, 11:16

Сообщение от Mikhaylo

хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе

Это основное правило.

Комментарии нужны:
1. Для функций (в C# такие комментарии начинаются с тройного слеша ///)
2. Иногда для переменных (если их назначение не очевидно из названия или использования)
3. Иногда для описания используемого алгоритма

Первый вариант формализован в большинстве современных IDE, как мы можем видет на картинке из этого сообщения:

Сообщение от Рыжий Лис

Уже давно изобретено до вас

Остальные варианты встречаются редко и не поддаются формализации.

Сообщение от Mikhaylo

Хотелось бы прокомментировать, почему первый аргумент 0. Навел на аргумент курсором, а там комментарий всплыл...

Обычно очевидно, почему 0.
Комментарии типа "function1(0 /* количество кошек */, a /* количество еды в килограммах */);" лишены смысла, так как это понятно 1) из названия аргументов функций, которые обычно можно увидеть в IDE 2) из комментариев первого типа (описание функции), которые тоже можно увидеть в IDE

Что касается числовых литералов. Допустимы 0 и 1 для начальных значений. Допустимы 1/2 для слагаемых/множителей. Другие литералы заменяются на константы с говорящими названиями. (Есть исключения типа "перебираем нечётные числа", в которых смысл литерала +2 очевиден).

Рыжий Лис · 23.11.2020, 11:21

Сообщение от Shamil1

Другие литералы заменяются на константы с говорящими названиями.

Это да. А ещё лучше на enum и сразу пишется

C#

1	return render(Status::InternalServerError, "index.html");

@Shamil1 · 23.11.2020, 11:28

Сообщение от Рыжий Лис

А ещё лучше на enum и сразу пишется

Согласен. Енум - это хорошо, когда у нас (по смыслу) есть перечисление. Статус - это всегда перечисление (ну, иногда можно bool, если их всего два).
Но есть ещё константы типа DefaultSize и т.п. Не должно быть кода типа "var a = new int[4];".

Рыжий Лис · 23.11.2020, 11:41

Сообщение от Shamil1

. Не должно быть кода типа "var a = new int[4];".

А что не так с этим кодом? Вполне норм. Только если структурой заменить:

C#

pub struct Buf {
    pub x: u32,
    pub y: u32,
    pub z: u32,
    pub zoom: u32,
}

Или

C#

pub struct Buf {
    buf: RawVec<u32>,
    len: usize,
}

@vantfiles · 23.11.2020, 11:42

Не по теме:

Mikhaylo, не подскажете, в чем картинку рисовали в посте #10 ?

Рыжий Лис · 23.11.2020, 11:47

Не по теме:

Так картинку стащили отсюда: http://dtris.sourceforge.net/d... index.html

@Shamil1 · 23.11.2020, 11:56

Сообщение от Рыжий Лис

А что не так с этим кодом?

А где в нём литералы?

@Mikhaylo · 23.11.2020, 20:08 **[ТС]**

Сообщение от Shamil1

Остальные варианты встречаются редко и не поддаются формализации.

Не знаю, я формализовал. См выше. Я ввел понятие внешней системы и успешно кручу им.
Есть правда трудности формализации:
1. Программист частично знаком с внешней системой
2. Программисту трудно дается разбирательство с внутренним устройством программы.
3. Программа в какой-то степени отражает внешнюю систему. (Например, если принтер как внешняя система не печатает букву Ё, то в программе будет условие проверки "принтер=ххх AND буква=Ё, то буква=Е". А иногда бывает, что программа не отражает внешнюю систему, например, вычисление корня квадратного может не учитывать, что очень часто извлекается корень из 49. Можно было бы сделать отражающий код:
если подкоренное число 49, то радикал = 7, иначе радикал = корень из подкоренного числа.)

Очень важный пример программ, которые не отражают окружение, это некоторые универсальные алгоритмы, универсальные библиотеки. В них предполагается произвольность входных данных, то есть окружение абстрактно. И об этом нужно писать в комментариях, это же ведь информация о внешней системе.

Добавлено через 25 минут
Абсолютно противоположный пример - программы, реализующие алгоритм точного управления с разомкнутым контуром предопределенным объектом управления. Если объект управления описывается уравнением y = f(x), то для управления его поведением следует создать программу реализующую обратную функцию x=f^-1(y*), где y* - целевое воздействие.
В итоге система, состоящая из объекта управления и управляющей программы реализует функцию равенства целевой функции и реального поведения y = f(x) = f(f^-1(y*)) = y*. Такая программа во всех отношениях отражает объект управления, который представляется как внешняя система для программы. Такая программа является идеальным объектом для принципа необходимого разнообразия Эшби.

Сложно?)

Добавлено через 7 минут
Эти идеальные программы редко имеют место быть, это первый момент, но в то же время, без разницы, что описывать - внешнюю систему или внутреннюю, это второй момент. Так как зная одну из них, можно получить другую, используя простую математическую операцию обращения функции. И так как внутренняя система записана в виде кода, который не требует комментирования, то внешнюю систему не следует комментировать. Достаточно сказать, что она является однозначным отражением (обращением) программы. Или наоборот.

@Mikhaylo · 24.11.2020, 08:31 **[ТС]**

Сообщение от Shamil1

Обычно очевидно, почему 0.

Обычно, да. Но может быть непонятно, так как "здесь 0, так как этот уровень игры без гравитации и соответственно время пойдет вспять". Или какой-нибудь подобный комментарий.

Заметьте: программист видит, что в функцию подставляется 0 и даже проанализировать может выполнение программы, но требуется комментарий. Причина - нет знания о внешней системе (добавили в игру необычный уровень или режим с невесомостью).

То есть, всякие рассуждения, что комментарии можно полностью устранить хорошими абстракциями, неверны. Так как не всегда у программиста есть подробные знания о внешней системе. Эти знания можно давать не только текстом, но и фотографиями, видео, погружением непосредственно в систему (в геймплей, как в рассматриваемом примере).

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	23.11.2020, 20:08 [ТС]	19
	Сообщение от Shamil1 Остальные варианты встречаются редко и не поддаются формализации. Не знаю, я формализовал. См выше. Я ввел понятие внешней системы и успешно кручу им. Есть правда трудности формализации: 1. Программист частично знаком с внешней системой 2. Программисту трудно дается разбирательство с внутренним устройством программы. 3. Программа в какой-то степени отражает внешнюю систему. (Например, если принтер как внешняя система не печатает букву Ё, то в программе будет условие проверки "принтер=ххх AND буква=Ё, то буква=Е". А иногда бывает, что программа не отражает внешнюю систему, например, вычисление корня квадратного может не учитывать, что очень часто извлекается корень из 49. Можно было бы сделать отражающий код: если подкоренное число 49, то радикал = 7, иначе радикал = корень из подкоренного числа.) Очень важный пример программ, которые не отражают окружение, это некоторые универсальные алгоритмы, универсальные библиотеки. В них предполагается произвольность входных данных, то есть окружение абстрактно. И об этом нужно писать в комментариях, это же ведь информация о внешней системе. Добавлено через 25 минут Абсолютно противоположный пример - программы, реализующие алгоритм точного управления с разомкнутым контуром предопределенным объектом управления. Если объект управления описывается уравнением y = f(x), то для управления его поведением следует создать программу реализующую обратную функцию x=f^-1(y), где y - целевое воздействие. В итоге система, состоящая из объекта управления и управляющей программы реализует функцию равенства целевой функции и реального поведения y = f(x) = f(f^-1(y)) = y. Такая программа во всех отношениях отражает объект управления, который представляется как внешняя система для программы. Такая программа является идеальным объектом для принципа необходимого разнообразия Эшби. Сложно?) Добавлено через 7 минут Эти идеальные программы редко имеют место быть, это первый момент, но в то же время, без разницы, что описывать - внешнюю систему или внутреннюю, это второй момент. Так как зная одну из них, можно получить другую, используя простую математическую операцию обращения функции. И так как внутренняя система записана в виде кода, который не требует комментирования, то внешнюю систему не следует комментировать. Достаточно сказать, что она является однозначным отражением (обращением) программы. Или наоборот. 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
		1
	Идеальные комментарии в программе 20.11.2020, 20:01. Показов 4648. Ответов 23 Метки нет (Все метки) Интересуюсь технологиями и техниками в программировании. Один из вопросов интересных - какие правила для написания хороших комментариев в программе. Есть правила для новичков - вроде "не пиши, что делает программа дословно", ну и правило, что хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе. Последнее утверждение, конечно, ложь, так как человек, изучающий программу, может быть не в курсе предметной области. Например, может быть комментарий "А принтер этой модели не умеет печатать букву Ё!". Я уже в соседней теме писал, что меня интересует IDE/ЯП для программиста, а не для компилятора/процессора. В существующих языках комментарий - это простая строка с любой ахинеей, которая предназначена для программиста, но не для компилятора. И в определенный момент я понял, что в моей IDE комментариев не будет в том виде, как в существующих языках. В моей IDE (которой ещё почти нет) комментарии заменят неким образом структурированные комментарии. Моя цель - понять, как структурировать. Ну и главный вопрос - как понять, что комментарии завершены, достаточны и понятны? 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	21.11.2020, 12:34 [ТС]	3
	Сообщение от Рыжий Лис Непонятно при чём здесь IDE и код. Все просто: IDE может помогать составлять хорошие комментарии. Мы привыкли, что комментарии - это просто набор произвольных букв. В этой теме предлагаю отвыкнуть.) Одна из простых идей - привязка комментария к любому элементу языка программирования. Мы помещаем комментарий сверху, снизу или справа от инструкции, точнее, строки с инструкцией или ее частью. Но не можем как-то удобно расположить комментарий, например, внутри вызова функции: Код function1(0, a); Хотелось бы прокомментировать, почему первый аргумент 0. Навел на аргумент курсором, а там комментарий всплыл... 0

Рыжий Лис Просто Лис 5965 / 3728 / 1097 Регистрация: 17.05.2012 Сообщений: 10,787 Записей в блоге: 9
	21.11.2020, 12:52	5
	Уже давно изобретено до вас Миниатюры 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	21.11.2020, 12:56 [ТС]	6
	Ох уж это приверженство plain-text programming language!))) Это мое определение для всех ЯП, к которым мы привыкли. Я намеренно стираю грань между IDE и ЯП, так как понимаю, что способы вывода и ввода информации - это тоже часть языка [программирования] и тоже подлежат стандартизации (как части языка). Добавлено через 1 минуту А вот картинка уже интереснее! 0

@vantfiles 1017 / 1905 / 178 Регистрация: 07.05.2013 Сообщений: 3,931 Записей в блоге: 12
	22.11.2020, 00:11	7
	Есть к примеру Doxygen https://www.doxygen.nl/index.html 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	22.11.2020, 09:01 [ТС]	8
	Я открыл пример доксигеновской документации http://dtris.sourceforge.net/d... index.html Я не знаю, может проект действительно сложный, но понятного мало, особенно когда смотришь на супер-схему взаимосвязей. Я так понимаю, Доксиген использует комментарии в программе и сам код, чтобы сгенерировать документацию, и больше никакой информации. vantfiles, спасибо, может действительно Доксиген поможет быстрее выявить существующие проблемы комментирования. Теперь я хочу сформулировать принципы идеального комментирования: 1. Работу программы комментировать не надо, лучше применяй хорошие абстракции. 2. Прокомментируй окружение программы, информация о внешних системах не содержится в коде. 3. Неподготовленный программист способен самостоятельно проанализировать код и может что-то знать про окружение (просто побывав в этом самом окружении в качестве тестировщика). Однако, возможны ситуации, когда код действительно сложный, а окружение полноценно изучить, побывав в нем, затруднительно. Добавлено через 13 минут 4. Комментатор сам может не знать окружение, плохо разбираться в своей программе или не уделять достаточного внимания комментированию. На уровне IDE эта проблема должна и может быть решена. Для этого IDE должна контролировать соблюдение принципов комментирования, я уж не говорю, что помогать с абстракциями в коде. 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	22.11.2020, 10:27 [ТС]	10
	Это вы про тот случай, когда алгоритм действительно сложный для понимания. А неподготовленный программист всё-таки может. Добавлю ещё один принцип: 5. Программа является отражением (зеркалом) окружения. Но, как правило, неточным отражением. Это означает, что, описывая окружение, становится отчасти понятно, как должна работать (как работает) программа. Этот принцип восходит к принципу необходимого разнообразия систем Эшби. Но надо учитывать, что разнообразие не всегда необходимое.))) С 5-ым принципом гораздо интереснее. Попробую продемонстрировать на примере: Кликните здесь для просмотра всего текста В этой схеме все связи равнозначны, хотя фактически можно выделить основные связи, а часть обозначить как вспомогательные, дополнительные, связи "на всякий случай" и прочие категории. Берём и расставляем для всех связей веса-комментарии (компилятор не берет в расчет эти веса). Основные связи пожирнее отобразить, вспомогательные потоньше. Это комментирование кода непосредственно. Можно также описать через внешнее окружение: написать, что для игрока в 3Д-Тетрис важны изображение стакана, фигурок (игровая сцена) и кнопки управления. Всякие там окна Start и окна Gameover/Congratulation менее важны, подсчет игровых очков тоже не суть. Это тоже расставит веса объектам, функциям, переменным, связям. Этой информации нет ни в коде, и основная проблема - программисты не знают, что это важно для понимания. Самое правильное описание окружения программы - это математическая модель окружения. Однако это дорого, сложно и не совсем необходимо, так как программа является инверсным отражением окружения (почти). Если есть код программы, то необходимость в матмодели окружении частично отпадает. Следует добавить немного той информации, которой не видно в "зеркале". Сложно понять, всю эту околофилософскую чушь про "зеркало", "необходимое разнообразие" и т.д. Чтобы справиться с этой сложностью, я для себя принял, что часто важной информацией об окружении является распределение частот (вероятностей) входных переменных. Например, у пульта телевизора 40 кнопок, и распределение частот нажатий на кнопки смещено к тому используются в основном пять кнопок: Power, Vol+, Vol-, Ch+, Ch-. Эта информация помогает выделить главные функции в ПО телевизора. Компилятору эта информация не нужна, в коде эта информация не содержится. 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	22.11.2020, 10:34 [ТС]	11
	Рыжий Лис, сейчас доберёмся до ваших кусков программ. Вы правильно подметили, что абстракции скрывают детали реализации. Тогда решение такое: то, что скрыто под абстракцией, считать внешним окружением, и тогда все встаёт на свои места. При чем забавно, что это окружение имеет модель в виде кода, который можно подглядеть (не всегда). 0

@Shamil1 Модератор 3077 / 2226 / 462 Регистрация: 26.03.2015 Сообщений: 8,626
	23.11.2020, 11:16	12
	Сообщение от Mikhaylo хорошо названные имена переменных, функций и объектов должны избавить программу от комментариев вовсе Это основное правило. Комментарии нужны: 1. Для функций (в C# такие комментарии начинаются с тройного слеша ///) 2. Иногда для переменных (если их назначение не очевидно из названия или использования) 3. Иногда для описания используемого алгоритма Первый вариант формализован в большинстве современных IDE, как мы можем видет на картинке из этого сообщения: Сообщение от Рыжий Лис Уже давно изобретено до вас Остальные варианты встречаются редко и не поддаются формализации. Сообщение от Mikhaylo Хотелось бы прокомментировать, почему первый аргумент 0. Навел на аргумент курсором, а там комментарий всплыл... Обычно очевидно, почему 0. Комментарии типа "function1(0 /* количество кошек /, a / количество еды в килограммах */);" лишены смысла, так как это понятно 1) из названия аргументов функций, которые обычно можно увидеть в IDE 2) из комментариев первого типа (описание функции), которые тоже можно увидеть в IDE Что касается числовых литералов. Допустимы 0 и 1 для начальных значений. Допустимы 1/2 для слагаемых/множителей. Другие литералы заменяются на константы с говорящими названиями. (Есть исключения типа "перебираем нечётные числа", в которых смысл литерала +2 очевиден). 0

@Shamil1 Модератор 3077 / 2226 / 462 Регистрация: 26.03.2015 Сообщений: 8,626
	23.11.2020, 11:28	14
	Сообщение от Рыжий Лис А ещё лучше на enum и сразу пишется Согласен. Енум - это хорошо, когда у нас (по смыслу) есть перечисление. Статус - это всегда перечисление (ну, иногда можно bool, если их всего два). Но есть ещё константы типа DefaultSize и т.п. Не должно быть кода типа "var a = new int[4];". 0

@vantfiles
	23.11.2020, 11:42 #16
	Не по теме: Mikhaylo, не подскажете, в чем картинку рисовали в посте #10 ? 0

Рыжий Лис
	23.11.2020, 11:47 #17
	Не по теме: Так картинку стащили отсюда: http://dtris.sourceforge.net/d... index.html 0

@Shamil1 Модератор 3077 / 2226 / 462 Регистрация: 26.03.2015 Сообщений: 8,626
	23.11.2020, 11:56	18
	Сообщение от Рыжий Лис А что не так с этим кодом? А где в нём литералы? 0

@Mikhaylo 673 / 547 / 74 Регистрация: 20.09.2014 Сообщений: 3,557
	24.11.2020, 08:31 [ТС]	20
	Сообщение от Shamil1 Обычно очевидно, почему 0. Обычно, да. Но может быть непонятно, так как "здесь 0, так как этот уровень игры без гравитации и соответственно время пойдет вспять". Или какой-нибудь подобный комментарий. Заметьте: программист видит, что в функцию подставляется 0 и даже проанализировать может выполнение программы, но требуется комментарий. Причина - нет знания о внешней системе (добавили в игру необычный уровень или режим с невесомостью). То есть, всякие рассуждения, что комментарии можно полностью устранить хорошими абстракциями, неверны. Так как не всегда у программиста есть подробные знания о внешней системе. Эти знания можно давать не только текстом, но и фотографиями, видео, погружением непосредственно в систему (в геймплей, как в рассматриваемом примере). 0