Кто-нибудь еще считает наименование классов и методов одной из самых сложных частей в программировании?
Поэтому я работаю над этим классом, который должен запрашивать справочную документацию у поставщика через веб-сервис. Я пытаюсь назвать это DocumentRetriever, VendorDocRequester, DocGetter, но они просто не звучат правильно. Я полчаса перебирал http://dictionary.com/, пытаясь найти подходящее слово.
Начинать программирование с дурных имен - все равно, что утром иметь очень плохой день, остальная часть дня идет вниз. Чувствуй меня?
42 ответа
То, что вы делаете сейчас, хорошо, и я настоятельно рекомендую вам придерживаться вашего текущего синтаксиса:
контекст + глагол + как
Я использую этот метод для присвоения имен функциям / методам, хранимым в SQL процессам и т. Д. Придерживаясь этого синтаксиса, он сделает ваши Intellisense/Code Panes намного более аккуратными. Поэтому вы хотите EmployeeGetByID() EmployeeAdd(), EmployeeDeleteByID(). Когда вы используете более грамматически правильный синтаксис, такой как GetEmployee(), AddEmployee(), вы увидите, что это становится действительно грязным, если у вас есть несколько Gets в одном классе, поскольку несвязанные вещи будут сгруппированы вместе.
Я похож на именование файлов с датами, вы хотите сказать, что 2009-01-07.log не 1-7-2009.log, потому что после того, как у вас их много, порядок становится совершенно бесполезным.
Один урок, который я усвоил, заключается в том, что если вы не можете найти имя для класса, в этом классе почти всегда что-то не так:
- тебе это не нужно
- это слишком много
Хорошее соглашение об именах должно минимизировать количество возможных имен, которые вы можете использовать для любой заданной переменной, класса, метода или функции. Если есть только одно возможное имя, у вас никогда не возникнет проблем с его запоминанием.
Для функций и для одноэлементных классов я тщательно исследую функцию, чтобы увидеть, является ли ее основная функция преобразованием одного вида вещи в другой тип вещи. Я использую этот термин очень свободно, но вы обнаружите, что ОГРОМНОЕ количество написанных вами функций, по сути, принимает что-то в одной форме и производит что-то в другой форме.
В вашем случае это звучит так, как будто ваш класс превращает URL в документ. Немного странно думать об этом таким образом, но совершенно правильно, и когда вы начнете искать этот паттерн, вы увидите его повсюду.
Когда я нахожу этот шаблон, я всегда называю функцию хFromгод назад
Поскольку ваша функция превращает URL в документ, я бы назвал его
DocumentFromUrl
Эта модель замечательно распространена. Например:
atoi -> IntFromString
GetWindowWidth -> WidthInPixelsFromHwnd // or DxFromWnd if you like Hungarian
CreateProcess -> ProcessFromCommandLine
Вы также можете использовать UrlToDocument если вам удобнее с этим заказом. Говорите ли вы хFromу или уToх, вероятно, дело вкуса, но я предпочитаю From порядок, потому что таким образом начало имени функции уже говорит вам, какой тип она возвращает.
Выберите одно соглашение и придерживайтесь его. Если вы осторожны, чтобы использовать те же имена, что и имена ваших классов в вашем хFromу функций, будет намного проще запомнить, какие имена вы использовали. Конечно, этот шаблон работает не для всех, но он работает там, где вы пишете код, который можно считать "функциональным".
Иногда нет хорошего названия для класса или метода, это случается со всеми нами. Однако зачастую невозможность придумать имя может указывать на что-то не так с вашим дизайном. У вашего метода слишком много обязанностей? Содержит ли ваш класс целостную идею?
Тема 1:
function programming_job(){
while (i make classes){
Give each class a name quickly; always fairly long and descriptive.
Implement and test each class to see what they really are.
while (not satisfied){
Re-visit each class and make small adjustments
}
}
}
Тема 2:
while(true){
if (any code smells bad){
rework, rename until at least somewhat better
}
}
Там нет Thread.sleep(...) нигде здесь.
Я также провожу много времени, беспокоясь о названиях всего, что может быть названо во время программирования. Я бы сказал, что это очень хорошо окупается. Иногда, когда я застреваю, я оставляю это на некоторое время, и во время перерыва на кофе я немного спрашиваю, есть ли у кого-нибудь хорошее предложение.
Для вашего класса я бы предложил VendorHelpDocRequester,
В книге Code Complete Стивом Макконнеллом есть хорошая глава по именованию переменных / классов / функций /...
Я думаю, что это побочный эффект.
Это не фактическое наименование, это сложно. Трудно то, что процесс именования заставляет вас столкнуться с ужасным фактом, что вы понятия не имеете, что, черт возьми, вы делаете.
Я на самом деле только что услышал эту цитату вчера через блог Signal vs. Noise на 37Signals, и я, безусловно, согласен с этим:
"В информатике есть только две сложные вещи: аннулирование кэша и именование". - Фил Карлтон
Это хорошо, что это сложно. Это заставляет вас думать о проблеме и о том, что на самом деле должен делать класс. Хорошие имена могут помочь привести к хорошему дизайну.
Согласовано. Мне нравится, чтобы мои имена типов и переменные были как можно более описательными, но при этом не были слишком ужасно длинными, но иногда есть только определенная концепция, для которой вы не можете найти подходящего слова.
В этом случае, это всегда помогает мне попросить коллег о вводе - даже если они в конечном счете не помогают, это обычно помогает мне, по крайней мере, объяснить это вслух и заставить мои колеса вращаться.
В прошлом месяце я просто писал о соглашениях об именах: http://caseysoftware.com/blog/useful-naming-conventions
Суть этого:
verbAdjectiveNounStructure - со структурой и прилагательным в качестве необязательных частей
Для глаголов я придерживаюсь глаголов действия: сохранять, удалять, уведомлять, обновлять или генерировать. Время от времени я использую "процесс", но только для того, чтобы специально ссылаться на очереди или рабочие резервы.
Для существительных я использую класс или объект, с которым взаимодействуют. В web2project это часто Задачи или Проекты. Если это Javascript, взаимодействующий со страницей, это может быть тело или таблица. Дело в том, что код четко описывает объект, с которым он взаимодействует.
Структура является необязательной, потому что она уникальна для ситуации. Экран распечатки может запросить список или массив. Одной из основных функций, используемых в списке проектов для web2project, является просто getProjectList. Он не изменяет базовые данные, только представление данных.
Прилагательные - это нечто совершенно другое. Они используются как модификаторы существительного. Нечто столь простое, как getOpenProjects, может быть легко реализовано с помощью getProjects и параметра switch, но это имеет тенденцию генерировать методы, которые требуют некоторого понимания базовых данных и / или структуры объекта... не обязательно того, что вы хотите поощрять. Имея более явные и конкретные функции, вы можете полностью обернуть и скрыть реализацию из кода, использующего его. Разве это не один из пунктов ОО?
Более чем просто присвоение имени классу, создание подходящей структуры пакета может быть сложной, но полезной задачей. Вы должны рассмотреть возможность разделения проблем ваших модулей и того, как они связаны с видением приложения.
Рассмотрим макет вашего приложения сейчас:
- Приложение
- VendorDocRequester (чтение из веб-службы и предоставление данных)
- VendorDocViewer (используйте реквестер для предоставления документации поставщика)
Я рискну предположить, что в нескольких классах происходит много всего. Если бы вы реорганизовали это в более ориентированный на MVC подход и позволили небольшим классам справляться с отдельными обязанностями, вы могли бы получить что-то вроде:
- Приложение
- VendorDocs
- модель
- Документ (простой объект, который содержит данные)
- WebServiceConsumer (разбираться с мелочами в веб-сервисе)
- контроллер
- DatabaseAdapter (обрабатывает персистентность, используя ORM или другой метод)
- WebServiceAdapter (используйте Consumer для захвата документа и помещения его в базу данных)
- Посмотреть
- HelpViewer (используйте DBAdapter, чтобы выплюнуть документацию)
Тогда ваши имена классов полагаются на пространство имен, чтобы обеспечить полный контекст. Сами классы могут быть неотъемлемо связаны с приложением без необходимости явно говорить об этом. Имена классов проще и легче определить в результате!
Еще одно очень важное предложение: сделайте себе одолжение и возьмите копию Head First Design Patterns. Это фантастическая, легко читаемая книга, которая поможет вам организовать ваше приложение и написать лучший код. Оценив шаблоны проектирования, вы поймете, что многие проблемы, с которыми вы сталкиваетесь, уже решены, и вы сможете включить эти решения в свой код.
Лео Броди в своей книге "Мышление вперед" писал, что наиболее трудной задачей для программиста является точное присвоение имен, и заявил, что наиболее важным инструментом программирования является тезаурус.
Попробуйте использовать тезаурус по адресу http://thesaurus.reference.com/.
Кроме того, не используйте венгерскую нотацию НИКОГДА, избегайте сокращений и будьте последовательны.
С наилучшими пожеланиями.
Короче:
Я согласен, что хорошие имена важны, но я не думаю, что вам нужно их искать, прежде чем внедрять любой ценой.
Конечно, лучше иметь хорошее имя с самого начала. Но если вы не можете придумать один за 2 минуты, переименование позже будет стоить меньше времени и является правильным выбором с точки зрения производительности.
Долго:
Как правило, часто не стоит слишком долго думать о названии перед внедрением. Если вы реализуете свой класс, называя его "Foo" или "Dsnfdkgx", при реализации вы видите, как вы должны были его назвать.
Особенно с Java+Eclipse, переименование вещей не представляет никакой проблемы, поскольку оно тщательно обрабатывает все ссылки во всех классах, предупреждает вас о конфликтах имен и т. Д. И пока класс еще не находится в репозитории контроля версий, я не буду Не думаю, что что-то не так с переименованием в 5 раз.
По сути, это вопрос того, как вы думаете о рефакторинге. Лично мне это нравится, хотя иногда это раздражает моих товарищей по команде, так как они верят, что никогда не трогают работающую систему. И из всего, что вы можете реорганизовать, изменение имен - это одна из самых безобидных вещей, которые вы можете сделать.
У этого класса есть только одно разумное имя:
HelpRequest
Не позволяйте деталям реализации отвлекать вас от смысла.
Почему бы не HelpDocumentServiceClient вроде "полный рот" или HelpDocumentClient... не важно, что это поставщик, дело в том, что это клиент веб-службы, которая имеет дело с документами справки.
И да, назвать это сложно.
Мне все равно, как долго имя метода или класса будет таким же длинным, как его описание и правильная библиотека. Давно прошли те дни, когда вы должны помнить, где находится каждая часть API.
Intelisense существует для всех основных языков. Поэтому при использовании стороннего API я предпочитаю использовать его intelisense для документации, а не "фактическую" документацию.
Имея это в виду, я в порядке, чтобы создать имя метода, такого как
StevesPostOnMethodNamesBeingLongOrShort
Долго - ну и что. Кто не использует 24-дюймовые экраны в эти дни!
Я придерживаюсь основ: VerbNoun(аргументы). Примеры: GetDoc(docID).
Нет необходимости фантазировать. Через год это будет легко понять, будь то вы или кто-то еще.
Язык, который вы используете для описания проблемы, это язык, который вы должны использовать для переменных, методов, объектов, классов и т. Д. В общем, существительные соответствуют объектам, а глаголы - методам соответствия. Если вам не хватает слов для описания проблемы, вам также не хватает полного понимания (спецификации) проблемы.
Если это просто выбор между набором имен, то это должно основываться на соглашениях, которые вы используете для построения системы. Если вы пришли в новое место, не раскрытое предыдущими соглашениями, то всегда стоит потратить некоторые усилия, пытаясь расширить их (правильно, последовательно), чтобы охватить это новое дело.
Если сомневаешься, спи на нем и выбери первое наиболее очевидное имя на следующее утро:-)
Если вы однажды проснетесь и поймете, что ошиблись, измените это прямо сейчас.
Павел.
Кстати: Document.fetch() довольно очевиден.
Я обнаружил, что у меня больше всего проблем с локальными переменными. Например, я хочу создать объект типа DocGetter. Так что я знаю, что это DocGetter. Почему мне нужно дать ему другое имя? Я обычно заканчиваю тем, что даю ему имя вроде dg (для DocGetter) или temp или что-то такое же неописательное.
Не забывайте, что шаблоны проектирования (не только GoF) являются хорошим способом предоставления общего словаря, и их имена следует использовать всякий раз, когда вы подходите к ситуации. Это даже поможет новичкам, знакомым с номенклатурой, быстро понять архитектуру. Предполагается, что этот класс, над которым вы работаете, будет действовать как Прокси или даже Фасад?
Я должен согласиться, что присвоение имен - это искусство. Это становится немного легче, если ваш класс следует определенному "шаблону поведения" (фабрика и т. Д.).
Разве документация поставщика не должна быть объектом? Я имею в виду, что это материально, а не просто как антропоморфизация части вашей программы. Итак, вы можете иметь VendorDocumentation класс с конструктором, который выбирает информацию. Я думаю, что если имя класса содержит глагол, часто что-то идет не так.
Я определенно чувствую тебя. И я чувствую твою боль. Каждое имя, о котором я думаю, просто кажется мне чепухой. Все это кажется настолько общим, и я хочу в конечном итоге научиться придавать немного чуткости и креативности моим именам, чтобы они действительно отражали то, что они описывают.
Одно из предложений, которое у меня есть, - обратиться к тезаурусу. У Word есть хороший пример, как и у Mac OS X. Это действительно может помочь мне выкинуть голову из облаков и дать мне хорошее начальное место, а также вдохновение.
DocumentFetcher? Трудно сказать без контекста.
Это может помочь вести себя как математик и позаимствовать / придумать лексикон для своего домена по ходу дела: выбирайте короткие простые слова, которые предлагают концепцию, не произнося ее каждый раз. Слишком часто я вижу длинные латинские фразы, которые превращаются в аббревиатуры, поэтому вам все равно нужен словарь для сокращений.
Это одна из причин наличия стандарта кодирования. Наличие стандарта, как правило, помогает придумывать имена, когда это необходимо. Это помогает освободить ваш разум, чтобы использовать его для других более интересных вещей! (-:
Я бы порекомендовал прочитать соответствующую главу Стив Макконнелла Code Complete ( ссылка на Amazon), которая включает несколько правил, которые помогают удобочитаемость и даже удобство обслуживания.
НТН
веселит,
обкрадывать
Ну, я вижу это с другой точки зрения, это одна из самых важных вещей, если вы хотите, чтобы ваш код был читаем для других.
Попробуйте сделать его описательным, и если это от третьей стороны, почему бы не включить имя [третьей стороны] в имя класса или метода.
Если это займет много времени, просто используйте любое имя, после слова вы можете изменить его.