Комментарии — зло

Комментарии — зло

Пожалуйста, хватит

Василий Половнёв, безработный

В этом выступлении не обсуждаются

• Clojure
• Функциональный Подход
• FreeBSD
• Erlang

Какие бывают комментарии

• закомментированный код;
• капитанские;
• комментарии-зарубки;
• вонючие.

Закомментированный код

			  // var fibonacci = function(n) {
			  //  if (n < 2){
			  //    return 1;
			  //  } else {
			  //    return fibonacci(n-2) + fibonacci(n-1);
			  //  }
			  // }
			  finallyMakeSomethingUseful();
			

Закомментированный код

Мешает чтению и пониманию кода, увеличивает риск пропустить работающий код.

Удаляйте без сомнений. Понадобится — возьмете из истории Гита.

Капитанские комментарии

				<!-- header --> <header id="header">
			

				// close connection
				connection.close();
			

				// if connection status is 0
				if (connection.status === 0)
			

Капитанские комментарии

Объясняют очевидное: что делает код. В них нет ни смысла, ни пользы, а глаз спотыкается.

Удаляйте. Или выражайте мысль в коде:

				if (connection.status === 0) → if (connection.isOpen())
			

Комментарии-зарубки

				// TODO: move it somewhere else
			

				// FIXME: sorry, I didn't have enough time to fix it properly
			

Комментарии-зарубки

Отвлекают, заставляют чувствовать себя виноватым.

Технический долг. Выносите такие комментарии в трекеры задач: Джира, Трелло, Бейскамп.

Вонючие комментарии

			  // 38 — line height in Firefox
				delta = event.deltaY * 38
			

				// make the user admin in the current project
				var membership = account.memberships.where({ userId: user.id }).first() 
				account.roles
				  .where({ membershipId: membership.id }
				  .updateAll(...))
			

Вонючие комментарии

Пытаются оправдать херовый код. Признак того, что вы не смогли выразить свою мысль ясно в коде.

Удаляйте и рефакторите код.

Вонючие комментарии

			  // 38 — line height in Firefox
				delta = event.deltaY * LINE_HEIGHT_IN_FIREFOX
			

				// make the user admin in the current project
				this.makeCurrentUserAdminInCurrentProject()
				var membership = account.memberships.where({ userId: user.id }).first()
				...
			

Спасибо

Пишите код, удаляйте комментарии, любите маму.

twitter.com/vazilla
vasily@polovnyov.ru