1

Тема: OFF: Построчное пояснение к элементам кода

Здравствуйте.Я как недавний участник форума, только начавший осваивать "AHK". Предлагаю  ввести правило, при публикации кода, построчно пояснять каждое действие, тем самым преобразить форум в наглядно-практическое пособие для новичков (таких как я). И облегчить понимание хода мыслей новичков, продвинутым программистам. Ведь, не так сложно  напечатать несколько строк пояснения, но зато исчезнет много лишних тем с повторяющимися вопросами.

2

Re: OFF: Построчное пояснение к элементам кода

Совсем народ обленился.

autoit@conference.jabber.ru - Конференция скриптового языка AutoIt на jabber.ru

3

Re: OFF: Построчное пояснение к элементам кода

pomapuo-cyber, боюсь, сделать это будет сложно. Нет, не добавить в «Правила…» само требование, а добиться от участников его выполнения.

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

Ведь, не так сложно  напечатать несколько строк пояснения,

Не сложно. Но если двадцать раз в день копировать из документации в код одно и то же — это очень быстро надоест.

но зато исчезнет много лишних тем с повторяющимися вопросами.

К сожалению, не исчезнет. Проверено.

Кто-то действительно не находит, кто-то не понимает… Но большая часть банально халтурит, ленится искать или вовсе гордо бьёт себя в грудь с криком: «Не знаю, и знать не хочу! Сделайте мне это!».

4

Re: OFF: Построчное пояснение к элементам кода

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

5

Re: OFF: Построчное пояснение к элементам кода

pomapuo-cyber, давайте будем говорить более предметно. Можете привести пример кода с комментариями, которые кажутся вам достаточными?

Разработка AHK-скриптов:
e-mail dfiveg@mail.ru
Telegram jollycoder

6

Re: OFF: Построчное пояснение к элементам кода

А комментарии, описывающие особенности и тонкие моменты алгоритма и без всяких правил обычно наличествуют.

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

7

Re: OFF: Построчное пояснение к элементам кода

Можете привести пример кода с комментариями, которые кажутся вам достаточными?

Тема:Проверка и чтение текстового файла. Отправил: Zohann

Loop, read, C:\Log File.txt
    last_line := A_LoopReadLine ; По завершении цикла здесь будет содержаться последняя строка.
If  last_line = "Время действовать"
    MsgBox "Время читать справку"

8

Re: OFF: Построчное пояснение к элементам кода

pomapuo-cyber пишет:
last_line := A_LoopReadLine ; По завершении цикла здесь будет содержаться последняя строка.

А как вы поняли, почему "По завершении цикла здесь будет содержаться последняя строка"?

Разработка AHK-скриптов:
e-mail dfiveg@mail.ru
Telegram jollycoder

9

Re: OFF: Построчное пояснение к элементам кода

В том то и дело, что я бы и не понял, если комментария не было. А тут на практике наглядный пример!

10

Re: OFF: Построчное пояснение к элементам кода

Неудачный выбрал пример, комментарий из справочника. Просто других не нашел, или плохо искал.

11

Re: OFF: Построчное пояснение к элементам кода

pomapuo-cyber пишет:

В том то и дело, что я бы и не понял, если комментария не было. А тут на практике наглядный пример!

А на вопрос всё же не ответили, т. е. скорее всего сути кода не поняли (либо не поняли по-крайней мере до тех пор, пока не прочитали соответствующую статью в справке). А какой смысл в практике, если теория не ясна? С другой стороны, как только осознаете теорию, данный комментарий становится излишним. Вот и приходим к тому, что говорил alexii — зачем переписывать в комментариях справку?
Поэтому каждую строчку уж точно комментировать не стоит, вполне достаточно обойтись описанием алгоритма. А если что-то непонятно, или, как чаще всего бывает, автор поленился писать комментарии, всегда можно задать вопрос.

Разработка AHK-скриптов:
e-mail dfiveg@mail.ru
Telegram jollycoder

12

Re: OFF: Построчное пояснение к элементам кода

pomapuo-cyber, учитесь пользоваться поиском, справочной литературой в любой форме. Не забывайте думать

AHK не входит в сферу моих интересов: ни профессиональных, ни увлечений. Тем не менее, читая код, могу понять более-менее, что происходит с тем или иным кодом.

Ваша просьба комментировать каждую строку кода приведет 1) к дублированию кода его описанием; 2) к распуханию примеров в 2-3 раза (за счет того, что комментарии на русском будут объемнее). Комментарий нужен чтобы объяснить некоторые сложные или неочевидные моменты кода.

( 2 * b ) || ! ( 2 * b )

13

Re: OFF: Построчное пояснение к элементам кода

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

14

Re: OFF: Построчное пояснение к элементам кода

документация носит больше ознакомительный характер

Где-то я уже это слышал. Только ник был другой.

15

Re: OFF: Построчное пояснение к элементам кода

Где-то я уже это слышал. Только ник был другой. roll

Озвучьте-ка в специальном разделе.

16 (изменено: Malcev, 2014-01-17 17:32:49)

Re: OFF: Построчное пояснение к элементам кода

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