Итак, я работаю над этим классом, который должен запрашивать справочную документацию у поставщика через веб-службу. Я пытаюсь назвать его DocumentRetriever, VendorDocRequester, DocGetter, но они просто не звучат правильно. В итоге я закончил просмотр dictionary.com в течение получаса, пытаясь найти подходящее слово.
Начать программирование с плохими именами, как с очень плохим днем волос утром, остальная часть дня идет вниз. Почувствуй меня?
То, что вы сейчас делаете, хорошо, и я настоятельно рекомендую вам придерживаться вашего текущего синтаксиса:
контекст + глагол + как
Я использую этот метод для обозначения функций/методов, хранимых процедур SQL и т.д. Соблюдая этот синтаксис, он будет держать ваши панели Intellisense/Code намного более аккуратными. Таким образом, вы хотите EmployeeGetByID() EmployeeAdd(), EmployeeDeleteByID(). Когда вы используете более грамматически корректный синтаксис, такой как GetEmployee(), AddEmployee(), вы увидите, что это становится очень грязным, если у вас есть несколько Gets в том же классе, что и несвязанные вещи будут сгруппированы вместе.
Я схожу на это с именами файлов с датами, вы хотите сказать, что 2009-01-07.log не 1-7-2009.log, потому что после того, как у вас есть куча, порядок становится абсолютно бесполезным.
Хорошее соглашение об именах должно минимизировать количество возможных имен, которые вы можете использовать для любой заданной переменной, класса, метода или функции. Если есть только одно возможное имя, у вас никогда не будет проблем с его запоминанием.
Для функций и для одноэлементных классов я тщательно изучаю функцию, чтобы увидеть, является ли ее основная функция преобразованием одного вида вещи в другое. Я использую этот термин очень свободно, но вы обнаружите, что огромное количество функций, которые вы пишете, в основном принимают что-то в одной форме и производят что-то в другой форме.
В вашем случае это звучит так, как ваш класс преобразует Url в документ. Немного странно думать об этом так, но совершенно правильно, и когда вы начнете искать этот шаблон, вы увидите его повсюду.
Когда я нахожу этот шаблон, я всегда называю функцию x From y.
Поскольку ваша функция преобразует Url в документ, я бы назвал его
DocumentFromUrl
Этот шаблон необычайно распространен. Например:
atoi -> IntFromString
GetWindowWidth -> WidthInPixelsFromHwnd // or DxFromWnd if you like Hungarian
CreateProcess -> ProcessFromCommandLine
Вы также можете использовать UrlToDocument, если вам удобнее с этим заказом. Если вы говорите, что x From y или y To x, вероятно, является вопросом вкуса, но я предпочитаю порядок From, потому что таким образом начало имени функции уже сообщает вам, какой тип он возвращает.
Выберите одно соглашение и придерживайтесь его. Если вы стараетесь использовать те же имена, что и имена классов, в своих функциях x From y, будет намного легче запомнить, какие имена вы использовали. Конечно, этот шаблон не работает для всего, но он работает там, где вы пишете код, который можно считать "функциональным".
Один урок, который я выучил, состоит в том, что если вы не можете найти имя для класса, в этом классе почти что-то не так:
Иногда нет хорошего имени для класса или метода, это случается со всеми нами. Часто, однако, невозможность придумать имя может быть намеком на что-то не так с вашим дизайном. У вашего метода слишком много обязанностей? Ваш класс инкапсулирует единую идею?
Тема 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 by Steve Mcconnell есть хорошая глава об именах переменных/классов/функций/...
Я только что услышал эту цитату вчера, через Блог Signal vs. Noise в 37Signals, и я, конечно же, согласен с ней:
"В" Информатике "есть только две тяжелые вещи: недействительность кеша и именование вещей". - Фил Карлтон
Я думаю, что это побочный эффект.
Это не настоящая именования. Что тяжело, что процесс именования заставляет вас столкнуться с ужасным фактом, что вы не представляете, что, черт возьми, вы делаете.
Хорошо, что это сложно. Это заставляет вас думать о проблеме и о том, что класс должен делать. Хорошие имена могут помочь привести к хорошему дизайну.
Согласен. Мне нравится сохранять имена и переменные типов как можно более наглядными, не слишком ужасающе длинными, но иногда есть только определенная концепция, из-за которой вы не можете найти хорошее слово.
В этом случае он всегда помогает мне попросить коллегу для ввода - даже если они в конечном итоге не помогут, это обычно помогает мне хотя бы объяснить это вслух и заставить мои колеса поворачиваться.
В прошлом месяце я просто писал о соглашениях об именах: http://caseysoftware.com/blog/useful-naming-conventions
Суть его:
verbAdjectiveNounStructure - со структурой и прилагательным в качестве дополнительных частей
Для глаголов я придерживаюсь глаголов действия: сохраняю, удаляю, уведомляю, обновляю или создаю. Время от времени я использую "процесс", но только для конкретного обращения к очередям или отставаниям в работе.
Для существительных я использую класс или объект, с которым мы взаимодействуем. В web2project это часто задачи или проекты. Если Javascript взаимодействует со страницей, это может быть тело или таблица. Дело в том, что код четко описывает объект, с которым он взаимодействует.
Структура является необязательной, поскольку она уникальна для ситуации. Экран списка может запрашивать список или массив. Одной из основных функций, используемых в списке проектов для web2project, является просто getProjectList. Он не изменяет базовые данные, а просто представляет данные.
прилагательные - это нечто совсем другое. Они используются в качестве модификаторов для существительного. Нечто простое, как getOpenProjects, может быть легко реализовано с помощью getProjects и параметра switch, но это имеет тенденцию генерировать методы, которые требуют довольно много понимания базовых данных и/или структуры объекта... не обязательно то, что вы хотите поощрять. Имея более явные и конкретные функции, вы можете полностью обернуть и скрыть реализацию из кода, используя его. Разве это не один из пунктов ОО?
Больше, чем просто называть класс, создание соответствующей структуры пакета может быть сложной, но полезной задачей. Вы должны учитывать разделение проблем ваших модулей и то, как они относятся к видению приложения.
Теперь рассмотрите расположение вашего приложения:
- App
- VendorDocRequester (прочитайте с веб-службы и предоставите данные)
- VendorDocViewer (используйте реквестер для предоставления документации поставщика)
Я бы рискнул догадаться, что внутри нескольких классов многое происходит. Если бы вы реорганизовали это на более подходящий подход MVC и разрешили небольшим классам выполнять индивидуальные обязанности, вы могли бы получить что-то вроде:
- App
- VendorDocs
- Модель
- Документ (простой объект, содержащий данные)
- WebServiceConsumer (работа с nitty gritty в веб-сервисе)
- Контроллер
- DatabaseAdapter (управление переносом с использованием ORM или другого метода)
- WebServiceAdapter (используйте "Потребитель" для захвата документа и вставьте его в базу данных)
- Просмотр
- HelpViewer (используйте DBAdapter для выделения документа)
Затем ваши имена классов полагаются на пространство имен, чтобы обеспечить полный контекст. Сами классы могут быть неотъемлемо связаны с приложением, не требуя явного объяснения. Имена классов проще и легче определить в результате!
Еще одно очень важное предложение: пожалуйста, сделайте себе одолжение и возьмите копию шаблонов Head First Design. Это фантастическая, простая книга, которая поможет вам организовать ваше приложение и написать лучший код. Признание шаблонов проектирования поможет вам понять, что многие проблемы, с которыми вы столкнулись, уже были решены, и вы сможете включить решения в свой код.
Лео Броди в своей книге "Thinking Forth" писал, что самая сложная задача для программиста - хорошо называть вещи, и он заявил, что самым важным инструментом программирования является тезаурус.
Попробуйте использовать тезаурус в http://thesaurus.reference.com/.
Помимо этого, не используйте венгерскую нотацию КОГДА-ЛИБО, избегайте сокращений и будьте последовательны.
С наилучшими пожеланиями.
Короче:
Я согласен с тем, что хорошие имена важны, но я не думаю, что вы должны найти их, прежде чем внедрять их любой ценой.
Конечно, лучше с самого начала иметь хорошее имя. Но если вы не можете придумать один за 2 минуты, переименование позже будет стоить меньше времени и является правильным выбором с точки зрения производительности.
Long
Как правило, часто не стоит слишком долго думать о имени перед его внедрением. Если вы реализуете свой класс, называя его "Foo" или "Dsnfdkgx", при реализации вы видите, что вы должны назвать его.
В частности, с Java + Eclipse, переименование вещей совсем не больно, так как оно тщательно обрабатывает все ссылки во всех классах, предупреждает вас о конфликтах имен и т.д. И пока класс еще не находится в репозитории управления версиями, Я не думаю, что что-то не так с переименованием 5 раз.
В принципе, это вопрос о том, как вы думаете о рефакторинге. Лично мне это нравится, хотя иногда это раздражает моих товарищей по команде, поскольку они верят, что никогда не прикасаются к запущенной системе. И из всего, что вы можете реорганизовать, изменение имен - одна из самых безобидных вещей, которые вы можете сделать.
Для этого класса существует только одно разумное имя:
HelpRequest
Не позволяйте деталям реализации отвлекать вас от значения.
Инвестируйте в хороший инструмент рефакторинга!
Почему не HelpDocumentServiceClient - это глоток, или HelpDocumentClient... неважно, что поставщик - это клиент для веб-службы, которая занимается документами справки.
И да, именование сложно.
Я придерживаюсь основ: VerbNoun (аргументы). Примеры: GetDoc (docID).
Нет необходимости получать фантазию. Это будет легко понять через год, будь то вы или кто-то еще.
Для меня мне все равно, как долго имя метода или класса до тех пор, пока его описательная и правильная библиотека. Давно прошли те дни, когда вы должны помнить, где находится каждая часть API.
Intelisense существует для всех основных языков. Поэтому при использовании стороннего API мне нравится использовать его intelisense для документации, а не для использования "фактической" документации.
С учетом этого я прав, чтобы создать имя метода, например
StevesPostOnMethodNamesBeingLongOrShort
Длинный - но так что. Кто не использует экраны 24inch в эти дни!
Я должен согласиться с тем, что именование - это искусство. Это становится немного легче, если ваш класс следит за определенной "схемой desigh" (factory и т.д.).
Нет, отладка - самая сложная вещь для меня!: -)
DocumentFetcher? Трудно сказать без контекста.
Это может помочь действовать как математик и заимствовать/придумывать лексику для вашего домена, когда вы идете: поселитесь на коротких простых словах, которые предлагают концепцию, не повторяя ее каждый раз. Слишком часто я вижу длинные латинские фразы, которые превращаются в акронимы, поэтому вам нужен словарь для акронимов.
Язык, который вы используете для описания проблемы, - это язык, который вы должны использовать для переменных, методов, объектов, классов и т.д. Свободно, существительные соответствуют объектам и методам совпадения глаголов. Если вам не хватает слов для описания проблемы, вам также не хватает полного понимания (спецификации) проблемы.
Если он просто выбирает между набором имен, тогда он должен управляться соглашениями, которые вы используете для построения системы. Если вы пришли в новое место, раскрытое предыдущими соглашениями, то всегда стоит потратить некоторое усилие на попытку расширить их (правильно, последовательно), чтобы охватить этот новый случай.
Если вы сомневаетесь, спите на нем и выберите первое наиболее очевидное имя, следующее утро: -)
Если вы однажды проснетесь и осознаете, что ошиблись, немедленно измените его.
Павел.
BTW: Document.fetch() довольно очевиден.
Я нахожу, что у меня большая проблема в локальных переменных. Например, я хочу создать объект типа DocGetter. Поэтому я знаю это DocGetter. Почему мне нужно дать ему другое имя? Я обычно заканчиваю тем, что давал ему имя, например, dg (для DocGetter) или temp, или что-то в равной степени безразличное.
Не забывайте, что шаблоны проектирования (а не только для GoF) - хороший способ обеспечить общий словарь, и их имена должны использоваться всякий раз, когда вы соответствуете ситуации. Это поможет даже новичкам, знакомым с номенклатурой, чтобы быстро понять архитектуру. Этот класс, над которым вы работаете, должен действовать как прокси-сервер или даже фасад?
Не следует ли документу поставщика быть объектом? Я имею в виду, что это осязаемо, а не как некоторая антропоморфизация части вашей программы. Таким образом, у вас может быть класс VendorDocumentation с конструктором, который извлекает информацию. Я думаю, что если имя класса содержит глагол, часто что-то пошло не так.
Я определенно чувствую тебя. И я чувствую твою боль. Каждое имя, о котором я думаю, просто кажется мусором для меня. Все это кажется таким общим, и я хочу в конечном итоге научиться вводить в свои имена немного таланта и творчества, что делает их действительно отражением того, что они описывают.
Одно из моих предложений - посоветоваться с тезаурусом. У Word есть хороший, как Mac OS X. Это действительно может помочь мне вырваться из облаков и дать мне хорошее начальное место, а также вдохновение.
Если имя объяснило бы программисту-планете, то, вероятно, нет необходимости его изменять.
Мне не сложно. Если вы не можете назвать это, возможно, вам это не понадобится. Чем лучше ваш дизайн, тем проще будет назвать то, что делает ваш дизайн.
Теперь временные переменные, это другая история.:)