Войти в систему

Home
    - Создать дневник
    - Написать в дневник
       - Подробный режим

LJ.Rossia.org
    - Новости сайта
    - Общие настройки
    - Sitemap
    - Оплата
    - ljr-fif

Редактировать...
    - Настройки
    - Список друзей
    - Дневник
    - Картинки
    - Пароль
    - Вид дневника

Сообщества

Настроить S2

Помощь
    - Забыли пароль?
    - FAQ
    - Тех. поддержка



Пишет superhuman ([info]superhuman)
@ 2018-01-23 20:27:00
Previous Entry  Add to memories!  Tell a Friend!  Next Entry
В каком стиле писать комментарии в коде или, скажем, отметки в системе версий? Конкретно, с большой буквы начинать, или маленькой? Закачивать точкой или нет?

Если бы они были гарантированно простыми, одним предложением, всегда бы писал с маленькой:
fixed this and that

Но иногда в одно предложение не ужаться, и выходит неразбериха. Не писать же:
fixed this and that. However, that and this is broken (в конце точка?)

Можно через запятую пробовать "fixed this and that, but that and this is broken". Потом запятой не хватает, появляется ";". Потом и этого не хватает. Писать через точку, но предложения начинать с маленькой? Криво. Писать всегда литературно, с большой буквы и точку в конце? Это уже слишком для большинства комментариев, оверкилл.

Долго меня мучает этот вопрос.

(Добавить комментарий)


[info]sadkov
2018-01-23 22:28 (ссылка)
Надо писать код так, чтобы комментарии не требовались. Например использовать внятные имена функций и переменных, а так же продвинутые элементы абстракции, вроде макросов. Скажем, можно вместо одного из видов комментариев ввести специальный тип или макрос, таким образом параметризовав комментарий и дав к нему доступ средствам IDE (например, можно сразу найти все однотипные коментарии).

(Ответить) (Ветвь дискуссии)


[info]sadkov
2018-01-23 22:44 (ссылка)
Например, в Common Lisp можно ввести `fix-me` макрос, вместо FIXME комментариев.

(Ответить) (Уровень выше)


[info]phantom
2018-01-23 23:05 (ссылка)
Это не всегда реально, чтобы вообще без комментариев. Ну, то есть я напишу так, что сам пойму, а никто другой - нет.

Да и не отвечает на вопрос, например, что делать с логами к системе версий. Или как именовать переменные. Те же проблемы, только ещё хуже с переменными.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-23 23:17 (ссылка)
>как именовать переменные
понятно и последовательно.

>Это не всегда реально, чтобы вообще без комментариев.
Всегда. Если надо что-то развернуто объяснить (например, как использовать API или как компоненты программы взаимодействуют), то выносится в отдельный фаил.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]phantom
2018-01-23 23:48 (ссылка)
Ну, вот функция:

unsigned char act (unsigned char f, unsigned char x, unsigned char y, unsigned char z) {
	unsigned char i, p, r;
	for (i = 0, r = 0; i < 8; ++i) {
		r >>= 1; p = 0;
		p += z & 1; p <<= 1;
		p += y & 1; p <<= 1;
		p += x & 1;
		r += 128 * ((f >> p) & 1);
		x >>= 1; y >>= 1; z >>= 1;
		//printf("r,p,x,y,z,f = %d,%d,%d,%d,%d,%d\n", r,p,x,y,z,f);
	}
	return r;
}


Тебе понятно, что она делает?.. И никому непонятно, пока я не объясню.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-24 09:27 (ссылка)
Хэш какой-то. Вынеси рассмотрение алгоритма в отдельную статью, дай на него ссылку, иначе твою функцию могут просто выкинуть, заменив своей.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]phantom
2018-01-24 09:41 (ссылка)
Не смогут заменить, потому что не знают, что она должна делать. А когда поймут, то переделывать не будут, потому что это конечный, оптимальный вариант, - ни добавить, ни убрать.

И что за статья отдельная? Академическая? Не будет опубликована, не инновационно.

Ссылки куда-то на веб из кода? Отвалятся вскоре.

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

Программа должна быть понятна сама по себе. Значит, должна содержать достаточно информацииб селф-контейнд.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-24 10:29 (ссылка)
>Не смогут заменить, потому что не знают, что она должна делать.

По использованию догадаются.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]phantom
2018-01-24 10:55 (ссылка)
Хорошо, продложим наш мысленный эксперимент. Вот единственное использование этой функции. Попробуй понять без комментариев, что функция делает, одна или вторая.

int clone (unsigned char operations[n], unsigned char arguments[n]) {
	unsigned int i, j, k, l;
	unsigned int r, previous = 0;
	//for (i = 0; i < n; ++i) printf("%d+%d, ", operations[i], arguments[i]);
	unsigned char f[n]; char m = 0; for (i = 0; i < n; ++i) if (operations[i]) f[m++] = i;
	unsigned char x[n]; for (i = 0; i < n; ++i) x[i] = arguments[i];
	while (1) {
		for (l = 0; l < m; ++l)
			for (i = 0; i < n; ++i) if (x[i]) for (j = 0; j < n; ++j) if (x[j]) for (k = 0; k < n; ++k) if (x[k])
				x[act(f[l], i, j, k)] = 1;
		r = 0; for (i = 0; i < n; ++i) r += x[i];
		if (r == previous) break; else previous = r;
	}
	//printf("r = %d\n", r);
	return r;
}

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-24 11:13 (ссылка)
Создает битмап. А уж для чего нужен битмап - дело десятое. Могу вообще весь код с битмапом выкинуть, заменив чем-то более вменяемым.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-24 11:14 (ссылка)
*Могут

(Ответить) (Уровень выше)


[info]phantom
2018-01-24 11:27 (ссылка)
Нет, к битмапам тут никакого отношения нету. Битмапы это 2 измерения, не так ли? Тут же вообще нет двойных массивов.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]sadkov
2018-01-24 11:45 (ссылка)
Битмап может иметь и три измерения, и N. Map - это отображение по английски. Т.е. отображение чего-то на биты.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]phantom
2018-01-24 12:01 (ссылка)
Пусть будет битмап одномерный. На что ты заменишь код? Не вижу понимания.

(Ответить) (Уровень выше)


[info]phantom
2018-01-24 10:57 (ссылка)
А, чуть не забыл,

#define n 256

(Ответить) (Уровень выше)


[info]perfect_kiss
2018-01-24 00:59 (ссылка)
) для тех, у кого трудности с выработкой чёткого списка собственных правил написания, гугло выдумало стайл гайды, в которых описаны комментарии в том числе

https://google.github.io/styleguide/cppguide.html#Comments
например для с++
https://www.google.com.ua/search?q=google+code+comment+style - там в первых позициях по остальным языкам стайл гайды

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

(Ответить) (Ветвь дискуссии)


[info]phantom
2018-01-24 09:35 (ссылка)
Этот народ не привык думать, поэтому жрёт, что дают. Особенно постыдно - добровольно делать то, что им Гугл и ему подобные предписывают. "Стайл гугла в первой позиции поиска стайла... в гугле", хехе, парадокс.

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]perfect_kiss
2018-01-24 12:00 (ссылка)
Куча альтернатив есть вообще ведь

(Ответить) (Уровень выше) (Ветвь дискуссии)


[info]phantom
2018-01-24 12:02 (ссылка)
Альтернатив своему стилю нет. Но его ещё выработать надо, потрудиться.

(Ответить) (Уровень выше)