Недавно в LinkedIn поделился эмоциями о том, что в большинстве случаев при работе с внешними заказчиками в коде нет комментариев. Вообще нет комментариев. И как же после этого приятно заглядывать в код, в котором комментарии есть.
К моему удивлению, там случился срач в котором мне пытались доказать, что комментарии врут, поэтому их писать не нужно.
Аргументы были не просто старые, а совсем уж древние, впервые их услышал лет 35 назад, еще когда только-только учился программировать. И с тех пор выслушивал их неоднократно.
Разбирать подобные домыслы в очередной раз нет ни сил, ни времени, ни желания. Если кто-то убежден, что есть самодокументирующийся код, то бог вам судья. Позволю себе только напомнить, что хорошо написанный код показывает только то, что и как сделано, но не может ответить на два очень важных вопроса:
- почему это сделано именно так, а не иначе?
- зачем вообще это было сделано?
Никакой "типа самодокументирующийся код" не может ответить на эти вопросы. А уж плохо написанный код не сможет вменяемо рассказать даже о том что именно было реализовано.
Первоначально я хотел на этом и закончить, но встретил в статье про переиздание знаменитой книги "Мифический человеко-месяц" вот такой абзац:
Однако есть и другая точка зрения на этот вопрос. Например, Мартин (Роберт, а не Джордж), автор книги «Чистый код», утверждает, что комментарии — это зло. Даже будучи среди исходного кода они всё равно могут стать неактуальными. «Не трать время на написание комментариев», – говорит Мартин. Вместо этого он предлагает более тщательно подходить к процессу именования переменных, методов и классов. Если всё делается правильно, то и необходимость в комментариях отпадает.
и подумал, что если уж так все запущено, то почему бы не попробовать привести пример кода с комментариями и без? Просто для того, чтобы каждый мог сделать собственные выводы.
Disclaimer. Приведенный код -- это черновик, который еще не компилировался и не тестировался.
Итак, вот фрагмент без комментариев:
|
template<typename T> void doAttemptToSwitchFromReadOnlyToReadWrite(T * objectToLock) { auto & globalList = getGlobalListFor(objectToLock); std::unique_lock globalListLock{ globalList._lock }; auto it = globalList._objects.find(objectToLock); if(it != globalList._objects.end()) { auto & lockInfo = it->second; if(AccessMode::ReadOnly != lockInfo._currentMode) throw std::runtime_error{ "doAttemptToSwitchFromReadOnlyToReadWrite: " "lockInfo._currentMode != AccessMode::ReadOnly " "in the global lock list" }; if(1u == lockInfo._ownersCount) { lockInfo._currentMode = AccessMode::ReadWrite; } else if(isWaitingQueueEmpty(lockInfo)) { OwnerCountForLockingUpgrateTrx ownerCounterTrx{ lockInfo }; const auto requestResult = makeWaitingAccessorInfoThenWait( globalListLock, lockInfo, AccessMode::ReadWrite); if(AccessRequestResult::granted != requestResult) throw PossibleDeadlock{ "doAttemptToSwitchFromReadOnlyToReadWrite: " "unable to upgrade ReadOnly lock to ReadWrite lock even " "after waiting" }; ownerCounterTrx.commit(); } else { throw PossibleDeadlock{ "doAttemptToSwitchFromReadOnlyToReadWrite: " "there is no possibility to upgrade ReadOnly lock " "to ReadWrite lock" }; } } else { throw std::runtime_error{ "doAttemptToSwitchFromReadOnlyToReadWrite: there is no " "information about objectToLock in the global lock list" }; } } |
А под катом он же, но в своем исходном виде, с комментариями. Посмотрите, подумайте, с каким кодом вам было бы комфортнее работать, если бы он вам достался на сопровождение. Я-то свои выводы уже давно сделал, чего и вам желаю.
