Q# Guia de estiloQ# Style Guide

Convenções GeraisGeneral Conventions

As convenções sugeridas neste guia destinam-se a ajudar a tornar os programas e bibliotecas escritos Q# de forma mais fácil de ler e compreender.The conventions suggested in this guide are intended to help make programs and libraries written in Q# easier to read and understand.

OrientaçãoGuidance

Sugerimos:We suggest:

  • Nunca ignore uma convenção a menos que o faça intencionalmente para fornecer um código mais legível e compreensível para os seus utilizadores.Never disregard a convention unless you’re doing so intentionally in order to provide more readable and understandable code for your users.

Convenções de NomeaçãoNaming Conventions

Ao oferecermos o Kit de Desenvolvimento Quântico, esforçamo-nos por nomes de funções e de operação que ajudam os desenvolvedores quânticos a escrever programas que são fáceis de ler e que minimizam a surpresa.In offering the Quantum Development Kit, we strive for function and operation names that help quantum developers write programs that are easy to read and that minimize surprise. Uma parte importante disso é que, quando escolhemos nomes para funções, operações e tipos, estamos a estabelecer o vocabulário que os programadores usam para expressar conceitos quânticos; com as nossas escolhas, ou ajudamos ou os dificultamos no seu esforço para comunicar claramente.An important part of that is that when we choose names for functions, operations, and types, we are establishing the vocabulary that programmers use to express quantum concepts; with our choices, we either help or hinder them in their effort to clearly communicate. Isto coloca-nos a responsabilidade de garantir que os nomes que introduzimos ofereçam clareza em vez de obscuridade.This places a responsibility on us to make sure that the names we introduce offer clarity rather than obscurity. Nesta secção, detalhamos como cumprimos esta obrigação em termos de orientação explícita que nos ajuda a fazer o melhor pela comunidade de Q# desenvolvimento.In this section, we detail how we meet this obligation in terms of explicit guidance that helps us do the best by the Q# development community.

Operações e FunçõesOperations and Functions

Uma das primeiras coisas que um nome deve estabelecer é se um dado símbolo representa uma função ou uma operação.One of the first things that a name should establish is whether a given symbol represents a function or an operation. A diferença entre funções e operações é fundamental para entender como um bloco de código se comporta.The difference between functions and operations is critical to understanding how a block of code behaves. Para comunicar a distinção entre funções e operações aos utilizadores, contamos com os Q# modelos de operações quânticas através da utilização de efeitos secundários.To communicate the distinction between functions and operations to users, we rely on that Q# models quantum operations through the use of side effects. Isto é, uma operação faz alguma coisa.That is, an operation does something.

Em contraste, as funções descrevem as relações matemáticas entre dados.By contrast, functions describe the mathematical relationships between data. A expressão Sin(PI() / 2.0) é 1.0 , e não implica nada sobre o estado de um programa ou seus qubits.The expression Sin(PI() / 2.0) is 1.0, and implies nothing about the state of a program or its qubits.

Resumindo, as operações fazem as coisas enquanto as funções são coisas.Summarizing, operations do things while functions are things. Esta distinção sugere que nomeamos as operações como verbos e funções como substantivos.This distinction suggests that we name operations as verbs and functions as nouns.

Nota

Quando um tipo definido pelo utilizador é declarado, uma nova função que constrói instâncias desse tipo é implicitamente definida ao mesmo tempo.When a user-defined type is declared, a new function that constructs instances of that type is implicitly defined at the same time. Nessa perspetiva, os tipos definidos pelo utilizador devem ser nomeados como substantivos para que tanto o tipo em si como a função de construtor tenham nomes consistentes.From that perspective, user-defined types should be named as nouns so that both the type itself and the constructor function have consistent names.

Quando razoável, certifique-se de que os nomes de operação começam com verbos que indicam claramente o efeito da operação.Where reasonable, ensure that operation names begin with verbs that clearly indicate the effect taken by the operation. Por exemplo:For example:

  • MeasureInteger
  • EstimateEnergy
  • SampleInt

Um caso que merece uma menção especial é quando uma operação toma outra operação como entrada e chama-a.One case that deserves special mention is when an operation takes another operation as input and calls it. Nestes casos, as medidas tomadas pela operação de entrada não são claras quando a operação exterior é definida, de modo a que o verbo certo não seja imediatamente claro.In such cases, the action taken by the input operation is not clear when the outer operation is defined, such that the right verb is not immediately clear. Recomendamos o Apply verbo, como em ApplyIf , e ApplyToEach ApplyToFirst .We recommend the verb Apply, as in ApplyIf, ApplyToEach, and ApplyToFirst. Outros verbos podem ser úteis também neste caso, como em IterateThroughCartesianPower .Other verbs may be useful in this case as well, as in IterateThroughCartesianPower.

VerboVerb Efeito EsperadoExpected Effect
AplicarApply Uma operação fornecida como entrada é chamadaAn operation provided as input is called
DeclararAssert Uma hipótese sobre o resultado de uma possível medição quântica é verificada por um simuladorA hypothesis about the outcome of a possible quantum measurement is checked by a simulator
Obter estimativaEstimate Um valor clássico é devolvido, representando uma estimativa extraída de uma ou mais mediçõesA classical value is returned, representing an estimate drawn from one or more measurements
MedirMeasure Uma medição quântica é realizada, e o seu resultado é devolvido ao utilizadorA quantum measurement is performed, and its result is returned to the user
PreparaçãoPrepare Um dado registo de qubits é inicializado num determinado estadoA given register of qubits is initialized into a particular state
SampleSample Um valor clássico é devolvido aleatoriamente de alguma distribuiçãoA classical value is returned at random from some distribution

Para funções, sugerimos evitar a utilização de verbos a favor de substantivos comuns (ver orientação sobre substantivos adequados abaixo) ou adjetivos:For functions, we suggest avoiding the use of verbs in favor of common nouns (see guidance on proper nouns below) or adjectives:

  • ConstantArray
  • Head
  • LookupFunction

Em particular, em quase todos os casos, sugerimos usar os particípios passados, quando apropriado, para indicar que um nome de função está fortemente ligado a uma ação ou efeito colateral em outros lugares de um programa quântico.In particular, in almost all cases, we suggest using past participles where appropriate to indicate that a function name is strongly connected to an action or side effect elsewhere in a quantum program. Por exemplo, ControlledOnInt usa a forma part participle do verbo "control" para indicar que a função age como um adjetivo para modificar o seu argumento.For example, ControlledOnInt uses the part participle form of the verb "control" to indicate that the function acts as an adjective to modify its argument. Este nome tem o benefício adicional de combinar a semântica do Controlled functor incorporado, como discutido mais abaixo.This name has the additional benefit of matching the semantics of the built-in Controlled functor, as discussed further below. Da mesma forma, os substantivos de agente podem ser usados para construir funções e nomes de UDT a partir de nomes de operação, como no caso do nome para uma Encoder UDT que está fortemente associada a Encode .Similarly, agent nouns can be used to construct function and UDT names from operation names, as in the case of the name Encoder for a UDT that is strongly associated with Encode.

Sugerimos:We suggest:

  • Utilize verbos para nomes de operação.Use verbs for operation names.
  • Utilize substantivos ou adjetivos para nomes de funções.Use nouns or adjectives for function names.
  • Utilize substantivos para tipos e atributos definidos pelo utilizador.Use nouns for user-defined types and attributes.
  • Para todos os nomes chamados, use CamelCase em forte preferência a , ou pascalCase snake_case ANGRY_CASE .For all callable names, use CamelCase in strong preference to pascalCase, snake_case, or ANGRY_CASE. Em particular, certifique-se de que os nomes de chamadas começam com letras maiúsculas.In particular, ensure that callable names start with uppercase letters.
  • Para todas as variáveis locais, utilize pascalCase em forte CamelCase snake_case preferência, ou ANGRY_CASE .For all local variables, use pascalCase in strong preference to CamelCase, snake_case, or ANGRY_CASE. Em particular, certifique-se de que as variáveis locais começam com letras minúsculas.In particular, ensure that local variables start with lowercase letters.
  • Evite a utilização de sublinhados _ em nomes de função e operação; onde são necessários níveis adicionais de hierarquia, utilize espaços de nome e pseudónimos de espaço de nome.Avoid the use of underscores _ in function and operation names; where additional levels of hierarchy are needed, use namespaces and namespace aliases.

Pontos de EntradaEntry Points

Ao definir um ponto de entrada num Q# programa, o Q# compilador reconhece o @EntryPoint() atributo exigindo que os pontos de entrada tenham um nome específico (por exemplo: main , ou Main __main__ ).When defining an entry point into a Q# program, the Q# compiler recognizes the @EntryPoint() attribute rather requiring that entry points have a particular name (e.g.: main, Main, or __main__). Ou seja, do ponto de vista de um desenvolvedor, os pontos de Q# entrada são operações ordinárias anotadas com @EntryPoint() .That is, from the perspective of a Q# developer, entry points are ordinary operations annotated with @EntryPoint(). Além disso, Q# os pontos de entrada podem ser pontos de entrada para toda uma aplicação (por exemplo, em Q# programas executáveis autónomos), ou podem ser uma interface entre um Q# programa e o programa anfitrião para uma aplicação (ou seja, quando se utiliza Q# com Python ou .NET), de modo que o nome "principal" pode ser enganador quando aplicado a um Q# ponto de entrada.Moreover, Q# entry points may be entry points for an entire application (for example, in Q# standalone executable programs), or may be an interface between a Q# program and the host program for an application (i.e.: when using Q# with Python or .NET), such that the name "main" could be misleading when applied to a Q# entry point.

Sugerimos a utilização de pontos de nomeação para refletir a utilização do @EntryPoint() atributo utilizando os conselhos gerais para as operações de nomeação acima enumeradas.We suggest using naming entry points to reflect the use of the @EntryPoint() attribute by using the general advice for naming operations listed above.

Sugerimos:We suggest:

  • Não nomeie as operações de ponto de entrada como "principais".Do not name entry point operations as "main."
  • Nomeie as operações de ponto de entrada como operações normais.Name entry point operations as ordinary operations.