Документирование кода. Правильно ли я делаю?

Question

[v- smerti]

Привет. Возле router path делаю комантарий c детальным описанием.
Есть два вопроса.
Стоит так делать?
Понятно ли я документирую?

/*
							отвечает за добавление нового человека в базу
							Принимает
								user/reg.Auth/{
									"login" : "%login%",
							        "email" : "%email%",
									"pass"  : "%pass%"
								}
						    %login% - логин добавляемого человека.
						    %email% - email человека
						    %pass%  - password человека

					        Возвращает
					            {
					                "operation"          : "true//false",
					                "operation_messages" : "%description%"
					            }
			                operation  -> true  - операция выполнена успешно
			                           -> false - произошла ошибка
		                    operation_messages -> operation  -> true  -> "Ok"
		                                       -> operation  -> false -> "Error description"

	*/
	router.GET("/reg.Auth/:json", auth.Create)

Answer 1

[Dokuro Тян]

А я вот не люблю документированный код. Если код написан хорошо и человек который читает его не тупой - всё понятно.

Да и как-то не красиво смотрится документированный код, ужс как не нравится)
Хотя это лично моё мнение.

Comments

[LittleFatNinja]

+

[Adamos]

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

Если вам придется работать с библиотекой, автор которой не потрудился хотя бы в комментариях пояснить форматы входных и выходных данных, вы будете радоваться красоте?

[Dokuro Тян]

Adamos: буду.

[Code_Jesus]

Что значит не люблю документированный код? Что за бред?!

Вам если прийдется работать с какой-то библиотекой, то вы будете устраивать реверс-инжиниринг каждому ее модулю?
А как тогда работать с API программы, код которой не доступен вообще? Есть грибы и получать с астрала имена методов и инструкции как формировать запрос на сервер?!

Answer 2

[Adamos]

Комментарии на английском - хорошая практика.
Если у вас возвращается переменная со значением true или false, логично назвать эту переменную по условию, которое истинно или ложно. Operation не может быть true, а вот, скажем, success - может. И комментарий станет излишним, по имени понятно. Аналогично, если в переменной operation_messages должны быть error descriptions, какого черта она называется иначе?
В общем, если в этом, вполне очевидном, случае верно назвать переменные, то комментарий сожмется до описания формата ввода и вывода. Остальное comments itself.

Comments

[Adamos]

В общем, раз уж задумываетесь над такими вещами, найдите и прочтите "Совершенный код" Макконнелла. Будет полезно.

[Александр Латышев]

Комментарии на английском - очень плохая практика.
Комментарии надо писать на языке общения команды :)

[Adamos]

Слово "практика" может иметь два значения в этом контексте. Правда, я имел в виду оба.
Ну ладно, вы не верите, что вам придется работать с иностранцами.
Но переменные и функции вы все равно будете называть не по-русски (или я слишком хорошо о вас думаю?). Так вот, имена в коде создают терминологию, принятую в решении данной задачи. И две терминологии - одна в коде, а другая в комментариях - только запутают того, кому придется читать этот код. А единую терминологию на разных языках выдержать все равно не получится, будет либо разнобой, либо тупая калька, которая ничем не лучше пиджина.

Answer 3

[Денис Инешин]

Имеет смысл, если у вас потом документация собирается автоматом, как например делают JSDoc, JavaDoc, PhpDoc и т.п. Если же нет, то проще и удобнее сделать отдельную Wiki-страницу с описанием API.

Comments

[v- smerti]

Сбор делает GoDoc

[Денис Инешин]

Владимир Грабко: В таком случае не сомневайтесь. Главное смотрите чтобы итоговая документация красиво выглядела и всё.

Answer 4

[Сергей]

C одной стороны правильно.
С другой чем больше комментариев, тем больше вероятность того что они не будут соответствовать коду.
Поэтому идеально, когда код документирует сам себя.