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

Question

Это вопрос, не зависящий от языка, но я забочусь о том, что люди предпочитают с точки зрения читабельности и удобства сопровождения ... Моя гипотетическая ситуация заключается в том, что я пишу функцию, для которой заданная последовательность будет возвращать копию со всеми повторяющимися элементами.удален и заказ полностью изменен

/*
*This is an extremely well written function to return a sequence containing 
*all the unique elements of OriginalSequence with their order reversed
*/    
ReturnSequence SequenceFunction(OriginalSequence)
{...}

ИЛИ

UniqueAndReversedSequence MakeSequenceUniqueAndReversed(OriginalSequence)
{....}

Выше предполагается , чтобы быть ясным примером использования комментариев в первом случае или использования очень подробных имен функций во второмописать действия функции.

Приветствия,

Ричард

Answer 1

Я предпочитаю подробное имя функции, поскольку оно делает сайт вызова более читабельным. Конечно, некоторые имена функций (например, ваш пример) могут быть очень длинными.

Возможно, лучшим примером для вашего примера функции будет ReverseAndDedupe. Ой, теперь немного яснее, что у нас есть функция с двумя обязанностями *. Возможно, было бы даже лучше разделить это на две функции: Reverse и Dedupe.

Теперь колл-сайт становится еще более читабельным:

Reverse(Dedupe(someSequence))

* Примечание . Мое эмпирическое правило заключается в том, что любая функция, содержащая в имени «и», имеет слишком много обязанностей и должна быть разделена на отдельные функции.

Answer 2

Я комментирую, где есть объяснение для того, чтобы описательное имя не могло адекватно передать. Если есть какая-то особенность с библиотекой, которая вынуждает меня делать что-то нестандартное или бесполезное при добавлении комментария в строку, я сделаю это, но в противном случае я полагаюсь на хорошо названные методы и не комментирую много - кроме пока я пишу код, и это для меня. Как правило, они удаляются, когда это делается.

Вообще говоря, комментарии заголовка функции - это просто больше строк, которые нужно поддерживать, и они требуют, чтобы читатель посмотрел как комментарий, так и код, а затем решил, что является правильным, если они не соответствуют. Очевидно, что правда всегда в коде. Комментарий может содержать X, но комментарии не компилируются в машинный код (как правило), поэтому ...

Комментируйте, когда это необходимо, и старайтесь хорошо называть вещи. Это то, что я делаю.

Answer 3

Я бы, наверное, сделал одно из них:

• Назовите его ReverseAndDedupe (или DedupeAndReverse, в зависимости от того, какой из них - я бы ожидал, что только Dedupe сохранит первое вхождение и отбросит более поздние, поэтому две операции не коммутируют) , Все функции обеспечивают выполнение some postcondition, поэтому Make может пойти на сокращение слишком длинного имени. Функции обычно не должны называться для типов, с которыми они работают, и если они есть, то они должны быть в согласованном формате. Так что Sequence, вероятно, можно удалить из предложенного вами имени, а если нет, то я бы назвал его Sequence_ReverseAndDedupe.

• Не создавать эту функцию вообще, убедитесь, что вызывающие абоненты могут либо Reverse(Dedupe(x)), либо Dedupe(Reverse(x)), в зависимости от того, что они на самом деле хотят. Им больше не нужно писать код, поэтому вопрос только в том, есть ли какая-то хитрая оптимизация, которая применима только тогда, когда вы делаете оба одновременно. Избегание промежуточной копии может быть уместным, но общий смысл в том, что если вы не можете назвать свою функцию кратко, убедитесь, что есть веская причина, почему она делает так много разных вещей.

• Назовите его ReversedAndDeduped, если он возвращает копию оригинальной последовательности - это трюк, который я взял из Python, где l.sort() сортирует список l на месте, а sorted(l) не делает изменить список l вообще.

• Дайте ему имя, относящееся к домену, в котором он используется, а не пытайтесь сделать его таким универсальным. Почему я дедуплирую и переворачиваю этот список? Может существовать некоторый термин «искусство», который означает список в этом состоянии, или некоторая функция, которая может быть выполнена только для такого списка. Так что я мог бы назвать его «Renuberate» (потому что перевернутый дедуплицированный список известен как список «в переименованной форме» или «MakeFrobbable» (потому что Frobbing требует этот формат).

Я бы также прокомментировал (или, что гораздо лучше, document it), чтобы объяснить, какой тип дедупликации он гарантирует (если есть - возможно, реализацию можно удалить бесплатно) что бы ему ни нравилось, пока он их всех получает).

Я бы не стал комментировать это «очень хорошо написано», хотя я мог бы прокомментировать «высокооптимизированный», чтобы означать, что «с этим кодом действительно сложно работать, но он работает как хлопушки, пожалуйста, не трогайте его, не запуская» все тесты производительности ".

Не думаю, что мне хотелось бы заходить так далеко, как названия функций из 5 слов, хотя я ожидаю, что это было в прошлом.

Answer 4

Даже с описательными именами вы все равно должны быть краткими.Я думаю, что то, что у вас есть в примере, является излишним.Я бы написал

UniqueSequence Reverse(Sequence)

Answer 5

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

Answer 6

Лично я предпочитаю второй способ - по названию функции легко увидеть, что она делает, - а поскольку код внутри функции хорошо написан, в любом случае будет легко понять, что именно происходит внутри нее.

Проблема, которую я нахожу с комментариями, состоит в том, что они очень быстро устаревают - нет проверки времени компиляции, чтобы убедиться, что ваш комментарий правильный!

Кроме того, вы не получите доступ к комментарию в местах, где эта функция фактически вызывается.

Очень субъективный вопрос!