Então, eu estou trabalhando nessa classe que deveria solicitar documentação de ajuda de um fornecedor por meio de um serviço da web. Tento nome dele DocumentRetriever
, VendorDocRequester
, DocGetter
, mas eles simplesmente não parece certo. Acabei navegando no dictionary.com por meia hora tentando encontrar uma palavra adequada.
Começar a programar com nomes ruins é como ter um dia de cabelos muito ruins pela manhã, o resto do dia desce a partir daí. Me sente?
naming-conventions
Haoest
fonte
fonte
Respostas:
O que você está fazendo agora é bom, e eu recomendo que você mantenha sua sintaxe atual, sendo:
contexto + verbo + como
Eu uso esse método para nomear funções / métodos, procs armazenados em SQL etc. Mantendo essa sintaxe, ele manterá os painéis Intellisense / Code muito mais organizados. Então você deseja EmployeeGetByID () EmployeeAdd (), EmployeeDeleteByID (). Quando você usa uma sintaxe gramaticalmente mais correta, como GetEmployee (), AddEmployee (), verá que isso fica realmente confuso se você tiver vários Gets na mesma classe, pois as coisas não relacionadas serão agrupadas.
Eu pareço isso com a nomeação de arquivos com datas, você quer dizer 2009-01-07.log e não 1-7-2009.log porque, depois de vários, a ordem se torna totalmente inútil.
fonte
InvalidateObsoleteQueries
?QueriesInvalidateObsolete
é difícil de ler e não faz sentido. Além disso, em C #, especialmente no Resharper, a ordem alfabética é irrelevante. Se você começar a digitar "emp", ReSharper irá dar-lheGetEmployee
,SetEmployee
e mesmoPopulateInactiveEmployeesList
.Uma lição que aprendi é que, se você não consegue encontrar um nome para uma turma, quase sempre há algo errado com essa turma:
fonte
Uma boa convenção de nomenclatura deve minimizar o número de nomes possíveis que você pode usar para qualquer variável, classe, método ou função. Se houver apenas um nome possível, você nunca terá problemas para se lembrar dele.
Para funções e para classes singleton, examino a função para ver se sua função básica é transformar um tipo de coisa em outro tipo de coisa. Estou usando esse termo muito livremente, mas você descobrirá que um enorme número de funções que você escreve toma essencialmente algo de uma forma e produz algo de outra forma.
No seu caso, parece que sua classe transforma um URL em um documento. É um pouco estranho pensar dessa maneira, mas perfeitamente correto, e quando você começar a procurar esse padrão, verá em todos os lugares.
Quando encontro esse padrão, sempre nomeio a função x
From
y .Como sua função transforma um URL em um documento, eu o chamaria
Esse padrão é notavelmente comum. Por exemplo:
Você também pode usar
UrlToDocument
se estiver mais confortável com esse pedido. Se você diz que xFrom
y ou yTo
x é provavelmente uma questão de gosto, mas prefiro aFrom
ordem, pois dessa forma o início do nome da função já diz qual tipo ele retorna.Escolha uma convenção e cumpra-a. Se você for cuidadoso ao usar os mesmos nomes dos nomes das classes nas funções x
From
y , será muito mais fácil lembrar quais nomes você usou. Obviamente, esse padrão não funciona para tudo, mas funciona onde você está escrevendo um código que pode ser considerado "funcional".fonte
Às vezes, não existe um bom nome para uma classe ou método, isso acontece com todos nós. Muitas vezes, no entanto, a incapacidade de criar um nome pode ser uma dica de algo errado com seu design. Seu método tem muitas responsabilidades? Sua classe contém uma ideia coerente?
fonte
Tópico 1:
Tópico 2:
Não há Thread.sleep (...) em qualquer lugar aqui.
fonte
Também passo muito tempo me preocupando com os nomes de qualquer coisa que possa receber um nome quando estou programando. Eu diria que compensa muito bem. Às vezes, quando estou preso, deixo por um tempo e, durante uma pausa para o café, pergunto um pouco se alguém tem uma boa sugestão.
Para sua classe, eu sugiro
VendorHelpDocRequester
.fonte
VendorHelpDocRequester.request()
. Eu preferiria apenas a forma plural como `VendorHelpDocs.request () 'O livro Code Complete, de Steve Mcconnell, tem um bom capítulo sobre como nomear variáveis / classes / funções / ...
fonte
Eu acho que isso é um efeito colateral.
Não é difícil dar nomes reais. O difícil é que o processo de nomeação o faz encarar o fato horrível de que você não tem idéia do que diabos está fazendo.
fonte
Na verdade, acabei de ouvir essa citação ontem, através do blog Signal vs. Noise, na 37Signals, e certamente concordo com isso:
"Existem apenas duas coisas difíceis na Ciência da Computação: invalidação de cache e nomeação de coisas." - Phil Karlton
fonte
É bom que seja difícil. Isso está forçando você a pensar sobre o problema e o que a classe realmente deve fazer. Bons nomes podem ajudar a levar a um bom design.
fonte
Acordado. Eu gosto de manter meus nomes e variáveis de tipo o mais descritivos possível sem ser muito longo, mas às vezes há apenas um certo conceito para o qual você não consegue encontrar uma boa palavra.
Nesse caso, sempre me ajuda a pedir sugestões a um colega de trabalho - mesmo que elas não ajudem, geralmente me ajuda a pelo menos explicar em voz alta e fazer minhas rodas girarem.
fonte
Eu estava escrevendo sobre convenções de nomenclatura no mês passado: http://caseysoftware.com/blog/useful-naming-conventions
A essência disso:
verbAdjectiveNounStructure - com Structure e Adjective como partes opcionais
Para verbos , mantenho os verbos de ação: salve, exclua, notifique, atualize ou gere. De vez em quando, eu uso "processo", mas apenas para me referir especificamente a filas ou atrasos de trabalho.
Para substantivos , eu uso a classe ou o objeto com o qual interagimos. No web2project, isso geralmente é Tarefas ou Projetos. Se o Javascript estiver interagindo com a página, pode ser corpo ou tabela. O ponto é que o código descreve claramente o objeto com o qual ele está interagindo.
A estrutura é opcional porque é exclusiva para a situação. Uma tela de listagem pode solicitar uma lista ou uma matriz. Uma das principais funções usadas na lista de projetos do web2project é simplesmente getProjectList. Não modifica os dados subjacentes, apenas a representação dos dados.
Os adjetivos são algo completamente diferente. Eles são usados como modificadores para o substantivo. Algo tão simples como getOpenProjects pode ser facilmente implementado com um getProjects e um parâmetro switch, mas isso tende a gerar métodos que exigem um pouco de entendimento dos dados e / ou estrutura subjacentes do objeto ... não necessariamente algo que você deseja incentivar. Por ter funções mais explícitas e específicas, você pode quebrar e ocultar completamente a implementação do código que a usa. Esse não é um dos pontos do OO?
fonte
Mais do que apenas nomear uma classe, criar uma estrutura de pacote apropriada pode ser um desafio difícil, mas gratificante. Você precisa considerar a separação das preocupações de seus módulos e como elas se relacionam com a visão do aplicativo.
Considere o layout do seu aplicativo agora:
Atrevo-me a adivinhar que há muita coisa acontecendo em algumas aulas. Se você refatorar isso para uma abordagem mais baseada em MVC e permitir que pequenas classes lidem com tarefas individuais, você pode acabar com algo como:
Em seguida, seus nomes de classe dependem do espaço para nome para fornecer o contexto completo. As próprias classes podem estar inerentemente relacionadas ao aplicativo sem precisar explicitamente dizer isso. Os nomes das classes são mais simples e fáceis de definir como resultado!
Outra sugestão muito importante: faça um favor a si mesmo e pegue uma cópia do Head First Design Patterns. É um livro fantástico e de fácil leitura que o ajudará a organizar seu aplicativo e escrever um código melhor. Apreciar os padrões de design o ajudará a entender que muitos dos problemas que você encontrou já foram resolvidos e você poderá incorporar as soluções ao seu código.
fonte
Leo Brodie, em seu livro "Thinking Forth", escreveu que a tarefa mais difícil para um programador era nomear as coisas bem, e afirmou que a ferramenta de programação mais importante é o tesauro.
Tente usar o dicionário de sinônimos em http://thesaurus.reference.com/ .
Além disso, não use a notação húngara EVER, evite abreviações e seja consistente.
Muitas felicidades.
fonte
Em resumo:
concordo que bons nomes são importantes, mas acho que você não precisa encontrá-los antes de implementá-los a todo custo.
É claro que é melhor ter um bom nome desde o início. Mas se você não conseguir criar um em dois minutos, renomear mais tarde custará menos tempo e é a escolha certa do ponto de vista da produtividade.
Longo:
Geralmente, geralmente não vale a pena pensar muito em um nome antes de implementar. Se você implementar sua classe, nomeie-a "Foo" ou "Dsnfdkgx", enquanto implementa, você vê como deveria ter nomeado.
Especialmente no Java + Eclipse, renomear as coisas não é nada trabalhoso, pois lida cuidadosamente com todas as referências em todas as classes, avisa sobre colisões de nomes, etc. E enquanto a classe ainda não estiver no repositório de controle de versão, eu não acho que há algo errado em renomeá-lo 5 vezes.
Basicamente, é uma questão de como você pensa sobre a refatoração. Pessoalmente, eu gosto, embora às vezes chateie meus companheiros de equipe, pois eles acreditam em nunca tocar em um sistema em execução . E de tudo que você pode refatorar, mudar de nome é uma das coisas mais inofensivas que você pode fazer.
fonte
Por que não o tipo HelpDocumentServiceClient, ou HelpDocumentClient ... não importa que seja um fornecedor, o ponto é que ele é um cliente de um serviço da Web que lida com documentos de Ajuda.
E sim, nomear é difícil.
fonte
Existe apenas um nome sensato para essa classe:
Não deixe que os detalhes da implementação o distraiam do significado.
fonte
HelpLibrary
para a aula, mas isso é pelo menos tão bom. Vale a pena ler as respostas primeiro!Invista em uma boa ferramenta de refatoração!
fonte
Eu me ater ao básico: VerbNoun (argumentos). Exemplos: GetDoc (docID).
Não é preciso ser chique. Será fácil entender daqui a um ano, seja você ou outra pessoa.
fonte
Para mim, não me importo com o tamanho de um método ou nome de classe, desde que seja descritivo e na biblioteca correta. Longe vão os dias em que você deve se lembrar de onde cada parte da API reside.
O Intelisense existe para todos os principais idiomas. Portanto, ao usar uma API de terceiros, gosto de usar o intelisense para a documentação, em vez de usar a documentação 'real'.
Com isso em mente, estou bem em criar um nome de método como
StevesPostOnMethodNamesBeingLongOrShort
Longo - mas e daí? Quem não usa telas de 24 polegadas hoje em dia!
fonte
Eu tenho que concordar que nomear é uma arte. Fica um pouco mais fácil se sua turma está seguindo um certo "padrão de desigh" (fábrica etc).
fonte
Esse é um dos motivos para ter um padrão de codificação. Ter um padrão tende a ajudar a criar nomes quando necessário. Isso ajuda a liberar sua mente para usar em outras coisas mais interessantes! (-:
Eu recomendo a leitura do capítulo relevante do Code Complete de Steve McConnell ( link da Amazon ), que inclui várias regras para ajudar na legibilidade e até na manutenção.
HTH
Felicidades,
Roubar
fonte
Não, a depuração é a coisa mais difícil para mim! :-)
fonte
DocumentFetcher? É difícil dizer sem contexto.
Pode ajudar a agir como um matemático e a emprestar / inventar um léxico para o seu domínio à medida que avança: escolha palavras curtas e simples que sugerem o conceito sem explicá-lo sempre. Muitas vezes eu vejo frases longa Latinate que se transformaram em siglas, tornando você precisa de um dicionário para as siglas de qualquer maneira .
fonte
A linguagem usada para descrever o problema é a linguagem que você deve usar para as variáveis, métodos, objetos, classes, etc. Vagamente, os substantivos correspondem aos objetos e os verbos aos métodos. Se estiver faltando palavras para descrever o problema, também estará faltando um entendimento completo (especificação) do problema.
Se for apenas escolher entre um conjunto de nomes, deve ser orientado pelas convenções que você está usando para criar o sistema. Se você chegou a um novo ponto, descoberto por convenções anteriores, sempre vale a pena gastar algum esforço tentando estendê-las (de maneira adequada e consistente) para cobrir esse novo caso.
Em caso de dúvida, durma e escolha o primeiro nome mais óbvio, na manhã seguinte :-)
Se você acordar um dia e perceber que estava errado, mude imediatamente.
Paulo.
BTW: Document.fetch () é bastante óbvio.
fonte
Acho que tenho mais problemas nas variáveis locais. Por exemplo, quero criar um objeto do tipo DocGetter. Então eu sei que é um DocGetter. Por que preciso dar outro nome a ele? Normalmente, acabo dando um nome como dg (para DocGetter) ou temp ou algo igualmente não-descritivo.
fonte
Não se esqueça que os padrões de design (não apenas os do GoF) são uma boa maneira de fornecer um vocabulário comum e seus nomes devem ser usados sempre que alguém se encaixa na situação. Isso até ajudará os recém-chegados familiarizados com a nomenclatura a entender rapidamente a arquitetura. Esta classe em que você está trabalhando deve agir como um proxy ou mesmo uma fachada?
fonte
A documentação do fornecedor não deve ser o objeto? Quero dizer, esse é tangível, e não apenas como uma antropomorfização de uma parte do seu programa. Portanto, você pode ter uma
VendorDocumentation
classe com um construtor que busca as informações. Eu acho que se um nome de classe contém um verbo, muitas vezes algo deu errado.fonte
Eu definitivamente sinto você. E eu sinto sua dor. Todo nome em que penso me parece um lixo. Tudo parece tão genérico e eu quero aprender a injetar um pouco de talento e criatividade em meus nomes, fazendo com que eles realmente reflitam o que descrevem.
Uma sugestão que tenho é consultar um dicionário de sinônimos. O Word é bom, assim como o Mac OS X. Isso pode realmente me ajudar a tirar a cabeça das nuvens e me dá um bom ponto de partida, além de alguma inspiração.
fonte
Se o nome se explicasse a um programador leigo, provavelmente não há necessidade de alterá-lo.
fonte