Рекомендуемые правила оформления кода

[Пепел Феникса]

Utkin, MaTBeu, захвалили прям.

мой код так никто и не понял
ну так и должно было быть.
а вот если добавить сигнатуру(полную) то он будет куда понятнее:

		const phL::LexicalScanner::Token& phL::LexicalScanner::Scanner::getToken()
		{
			if((*cache_it).getIdent()==L_EOF)return cache.back();
			if(cache_it>=cache.end())
				Scan();
			cache_it++;
			return *cache_it;
		}

ведь так уже куда яснее что он делает?

[MaTBeu]

Сообщение от Пепел Феникса

Utkin, MaTBeu, захвалили прям.

мой код так никто и не понял
ну так и должно было быть.
а вот если добавить сигнатуру(полную) то он будет куда понятнее:

		const Token& phL::LexicalScanner::Scanner::getToken()
		{
			if((*cache_it).getIdent()==L_EOF)
                                             return cache.back();
			if(cache_it>=cache.end())
				Scan();
			cache_it++;
			return *cache_it;
		}

ведь так уже куда яснее что он делает?

Если честно, код как-то пропустил. С сигнатурой стабильно понятнее. Хотя метод

(*cache_it).getIdent()

сначала прочитал как

(*cache_it).getIndent()

то есть не взять идентификатор, а взять отступ.

И еще вопрос - почему класс Token не внутри нэймспейса?

[Bustle]

Господи, а это ещё зачем?

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

Согласен со стилем документирования в посте #45.
Но и когда нужно то коменчу то, что нужно.

[Utkin]

Вам комментарии на каждой строке не помогли бы даже в таком коде

Отлично помогают . Эти строки позволили мне успешно перенести решение на C# при том, что общий объем кода вполне нормальный. И несмотря на то что сам код читается плохо.

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

Вы написали, что мой стиль студенческий, я Вам привел пример, где это работает. Я подвел итог, что Вас не устраивает? Это совсем не придирка к словам. Между прочим никто из Вас так и не сказал чем занимается данная функция. Если бы Пепел Феникса не подымал вопрос о лексических анализаторах ранее, я бы подбросил другой код. Уверен Вы бы и его не разобрали. Кстати, я присылал ему исходники анализатора. При желании он может найти данный фрагмент (ну может с небольшими отличиями в зависимости от версии).

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

Я и не спорю. Не помню, чтобы я писал что JavaDoc это плохо.

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

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

[Пепел Феникса]

И еще вопрос - почему класс Token не внутри нэймспейса?

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

Кстати, я присылал ему исходники анализатора.

я так пока и не читал его.
пока все не до этого + пока вроде свое идет более менее четко.

[MaTBeu]

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

Уверен Вы бы и его не разобрали.

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

Я тоже занимался лексическим и синтаксическим анализом. А насчет вашего высказывания есть отличная поговорка: "Если мне плевать на что-то, это не значит, что я в этом не разбираюсь."

[Человек_Борща]

Если мало знаний - ты вы и с "КЭП" комментариями не поймете, что делает код.

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

Я не имею базы знаний о языке на котором привел код Феникс, следовательно я не понимаю что он делает. Число символически, код - намекает на C++, но это не он. Не припоминаю там :: и т.д. Но если бы и знал синтаксис(язык), я бы всеравно пошёл смотреть сам класс Cache т.к. мне надо знать что делает каждый его метод. Без этого я не узнаю, что делает код.

[Пепел Феникса]

Я не имею базы знаний о языке на котором привел код Феникс, следовательно я не понимаю что он делает. Число символически, код - намекает на C++, но это не он. Не припоминаю там :: и т.д.

это полностью С++.
просто вы видимо пространства имен не изучали

[Utkin]

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

Я и не беру Вас на понт .

Я тоже занимался лексическим и синтаксическим анализом.

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

я пришел сюда обсудить приемы документирования

Это и так понятно - суете документирование где надо и где не надо. Речь в теме вообще-то не совсем о документировании. И данный флейм тоже не из него вырос.

Делайте ставку на то, что человек, который будет читать ваш код, будет иметь уровень знаний не ниже вашего.

Все правильно, я знал что Пепел Феникса в теме. Но а то что MaTBeu, имеет высокий уровень знаний и так понятно всем кто достаточное время находится на форуме.

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

Маразм крепчал.

[Человек_Борща]

Маразм крепчал.

Позволю не согласится. Вы сидите уже 2 часа над размышлением обьяснения ваших мыслей компьютерным языком. И тут ЭВРИКА вы знаете как это сделать, НО мысли такого плана очень быстро растворяются.


Я сразу открываю начало комментария и пишу мысли. Вот об этом я говорю. Об своём способе комментирования кода я уже написал.