// total_hours_wasted_here = 42
// I am not sure if we need this, but too scared to delete.
// When I wrote this, only God and I understood what I was doing
// Now, God only knows
return 1; # returns 1
// somedev1–6/7/02 Adding temporary tracking of Login screen
// somedev2–5/22/07 Temporary my ass
// I am not responsible of this code.
// They made me write it, against my will.
Тезисы
■ Пишите код как документацию.
■ Документируйте емким текстом.
■ Иногда код не может быть простым – документируйте!
Задание
Если у вас уже имеется некоторый опыт работы с проектом, проанализируйте места кода, которые вы хорошо знаете, и попытайтесь поставить себя на место человека, который видит этот код впервые. Смогли бы вы понять, что этот код делает? Не показалось бы вам, что было бы проще, окажись в том или ином месте текстовое описание правил выполнения или логики приложения?
История из жизни
На одном из проектов, где я работал, было принято решение комментировать весь написанный код, независимо от того, насколько он прост и понятен. Разработчики любят предсказуемость и простоту, однако оказавшись в ситуации, где формализм существует ради формализма, вы в итоге получаете что-то такое:
// check if operation was a success
if (isSuccess) {
// return success marker