gnome-devel-docs master - en to pt_BR translation catalogue (531 entries)

note: (itstool) path: info/desc
en: Other style guides and books about organizing free software projects
pt_BR: Outros guias de estilo e livros sobre organização de projetos de software livre

note: (itstool) path: page/title
en: Additional Materials
pt_BR: Materiais adicionais

note: (itstool) path: page/p
en: Here we give you links to other materials that you may want to read. These will teach you a lot about how to work on large distributed teams of free software developers, and about good programming style in general.
pt_BR: Aqui nós fornecemos links para outros materiais que você pode querer ler. Eles o ensinarão muito sobre como trabalhar em equipes grandes e distribuídas de desenvolvedores de software livre, e sobre bom estilo de programação em geral.

note: (itstool) path: item/p
en: <link href="http://producingoss.com/">Producing Open Source Software</link>, by Karl Fogel. This is a truly excellent book of good practices that free software projects should follow. This is about <em>social aspects</em> of the project: how to treat contributors, how to organize and moderate communication, how to deal with non-profit foundations. If you ask yourself at any time, "how should I deal with $human_situation in the project?", this book may provide the answer.
pt_BR: <link href="http://producingoss.com/">Producing Open Source Software</link> (Produzindo Software de Código Aberto), por Karl Fogel. Esse é realmente um excelente livro para boas práticas que projetos de software livre devem seguir. Trata sobre <em>aspectos sociais</em> do projeto: como tratar contribuidores, como organizar e moderar comunicação, como lidar com fundações sem fins lucrativos. Se você em algum momento se perguntar “como eu deveria lidar com $situação_humana no projeto?”, este livro pode lhe fornecer a resposta.

note: (itstool) path: item/p
en: <link href="http://www.gnu.org/prep/standards/">GNU Coding Standards</link>. This is an old document, but it still has lots of excellent advice. It talks about C coding style, issues when dealing with plug-in systems, common option names for command-line programs, conventions for Makefiles, and some very GNU-ish details like using Texinfo for documentation.
pt_BR: <link href="http://www.gnu.org/prep/standards/">GNU Coding Standards</link> (Padrões de codificação GNU). Esse é um documento antigo, mas ele ainda possui muitos excelentes conselhos. Ele fala sobre estilo de codificação C, questões ao lidar com sistemas de plug-in, nomes comuns de opções para programas de linha de comando, convenções para Makefiles e alguns detalhes bem relacionados só GNU, como o uso de Texinfo para documentação

note: (itstool) path: item/p
en: <link href="https://www.kernel.org/doc/Documentation/process/coding-style.rst"> Linux Kernel Coding Style</link>. Explains the rationale for "big indentation", brace placement, concise but unambiguous naming, and centralized exit of functions.
pt_BR: <link href="https://www.kernel.org/doc/Documentation/process/coding-style.rst"> Linux Kernel Coding Style</link> (Estilo de Codificação do Kernel Linux). Explica a fundamentação para o “recuo grande”, posicionamento de chaves, nomenclatura concisa sem ser ambígua e saída centralizada de funções.

note: (itstool) path: info/desc
en: Backwards compatibility in APIs
pt_BR: Compatibilidade reversa nas APIs

note: (itstool) path: page/title
en: API stability
pt_BR: Estabilidade de API

note: (itstool) path: synopsis/title
en: Summary
pt_BR: Resumo

note: (itstool) path: item/p
en: Define API stability guarantees for your project. (<link xref="#stability"/>)
pt_BR: Defina garantias de estabilidade de API para seu projeto. (<link xref="#stability"/>)

note: (itstool) path: item/p
en: Ensure version numbers are changed as appropriate when API changes. (<link xref="#versioning"/>)
pt_BR: Certifique-se de que números de versão sejam alterados conforme apropriado quando a API é alterada. (<link xref="#versioning"/>)

note: (itstool) path: section/title
en: API and ABI
pt_BR: API e ABI

note: (itstool) path: section/p
en: At a high level, an API – <em>Application Programming Interface</em> – is the boundary between two components when developing against them. It is closely related to an ABI – <em>Application Binary Interface</em> – which is the boundary at runtime. It defines the possible ways in which other components can interact with a component. More concretely, this normally means the C headers of a library form its API, and compiled library symbols its ABI. The difference between an API and ABI is given by compilation of the code: there are certain things in a C header, such as <code>#define</code>s, which can cause a library’s API to change without changing its ABI. But these differences are mostly academic, and for all practical purposes, API and ABI can be treated interchangeably.
pt_BR: Em um nível alto, uma API – <em>Application Programming Interface</em> ou interface de programação de aplicação – é o limite entre dois componentes quando se está desenvolvendo para eles. Ela está intimamente relacionada a uma ABI – <em>Application Binary Interface</em> ou interface binária de aplicação – que é o limite em tempo real. Ela define as formas possíveis nas quais outros componentes podem interagir com um componente. Mais concretamente, ela normalmente significa que os cabeçalhos C de uma biblioteca formam sua API, e biblioteca compilada simboliza sua ABI. A diferença entre uma API e uma ABI é dada pela compilação do código: há certas coisas em um cabeçalho C, tal como <code>#define</code>s, que podem fazer com que uma API da biblioteca seja alterada sem alterar sua ABI. Mas essas diferenças são em sua maioria acadêmicas e, para todos os propósitos práticos, API e ABI podem ser tratados de forma intercambiável.

note: (itstool) path: section/p
en: Examples of API-incompatible changes to a C function would be to add a new parameter, change the function’s return type, or remove a parameter.
pt_BR: Exemplos de alterações incompatíveis com API para uma função C seria adicionar um novo parâmetro, alterar o tipo de retorno da função ou remover um parâmetro.

note: (itstool) path: section/p
en: However, many other parts of a project can form an API. If a daemon exposes itself on D-Bus, the interfaces exported there form an API. Similarly, if a C API is exposed in higher level languages by use of GIR, the GIR file forms another API — if it changes, any higher level code using it must also change.
pt_BR: Porém, muitas outras partes de um projeto podem formar uma API. Se um daemon se expõe no D-Bus, as interfaces exportadas lá formam uma API. Similarmente, se uma API C é exposta em linguagens de alto nível pelo uso de GIR, o arquivo GIR forma uma outra API — se ela é alterada, qualquer código de alto nível usando-a também é alterado.

note: (itstool) path: section/p
en: Other examples of more unusual APIs are configuration file locations and formats, and GSettings schemas. Any changes to these could require code using your library to change.
pt_BR: Outros exemplos de APIs mais incomuns são locais e formatos de arquivos de configuração, e esquemas de GSettings. Quaisquer alterações nestes poderia exigir que o código usando sua biblioteca seja alterado.

note: (itstool) path: section/title
en: Stability
pt_BR: Estabilidade

note: (itstool) path: section/p
en: API stability refers to some level of guarantee from a project that its API will only change in defined ways in the future, or will not change at all. Generally, an API is considered ‘stable’ if it commits to backwards-compatibility (defined below); but APIs could also commit to being unstable or even forwards-compatible. The purpose of API stability guarantees is to allow people to use your project from their own code without worrying about constantly updating their code to keep up with API changes. Typical API stability guarantees mean that code which is compiled against one version of a library will run without problems against all future versions of that library with the same major version number — or similarly that code which runs against a daemon will continue to run against all future versions of that daemon with the same major version number.
pt_BR: Estabilidade da API se refere a algum nível de garantia de um projeto que sua API será alterada apenas em formas definidas no futuro, ou jamais será alterada. Geralmente, um API é considerada ‘estável’ se ela se compromete em manter compatibilidade com versões anteriores (definido abaixo); mas APIs pode também se comprometer em ser instáveis ou até mesmo compatíveis com versões posteriores. O propósito das garantias de estabilidade de API é permitir que as pessoas usem seu projeto para seus próprios código se preocupar em atualizar constantemente seu código para se manter em dia com as alterações da API. Garantias comuns de estabilidade de API significa que o código que é compilado com uma versão de uma biblioteca vai funcionar sem problemas contra todas versões futuras daquela biblioteca com o mesmo número de versão maior — ou similarmente àquele código que funciona com um daemon vai continuar a funcionar em todas as versões futuras daquele daemon com o mesmo número de versão maior.

note: (itstool) path: section/p
en: It is possible to apply different levels of API stability to components within a project. For example, the core functions in a library could be stable, and hence their API left unchanged in future; while the newer, less core functions could be left unstable and allowed to change wildly until the right design is found, at which point they could be marked as stable.
pt_BR: É possível aplicar diferentes níveis de estabilidade de API a componentes dentro de um projeto. Por exemplo, as funções centrais em uma biblioteca poderiam ser estáveis e, consequentemente, sua API mantida inalterada no futuro; enquanto as funções mais novas e menos centrais serem mantidas instáveis e poderem ser alteradas descontroladamente até que o design certo seja encontrado, ponto no qual elas poderiam ser marcadas como estáveis.

note: (itstool) path: section/p
en: Several types of stability commonly considered:
pt_BR: Vários tipos de estabilidade comumente considerados:

note: (itstool) path: item/title
en: Unstable
pt_BR: Instável (unstable)

note: (itstool) path: item/p
en: The API could change or be removed in future.
pt_BR: A API poderia alterar ou ser removida no futuro.

note: (itstool) path: item/title
en: Backwards compatible
pt_BR: Compatibilidade com versões anteriores

note: (itstool) path: item/p
en: Only changes which permit code compiled against the unmodified API to continue running against the modified API are allowed (for example, functions cannot be removed).
pt_BR: Apenas alterações que permitem código compilado com a API não modificada para continuar funcionando com a API modificada são permitidos (por exemplo, funções não podem ser removidas).

note: (itstool) path: item/title
en: Forwards compatible
pt_BR: Compatibilidade com versões posteriores

note: (itstool) path: item/p
en: Only changes which permit code compiled against the modified API to run against the unmodified API are allowed (for example, functions cannot be added).
pt_BR: Apenas alterações que permitem código compilado com a API modificada para funcionar com a API modificada são permitidos (por exemplo, funções não podem ser adicionadas).

note: (itstool) path: item/title
en: Totally stable
pt_BR: Totalmente estável

note: (itstool) path: item/p
en: No changes are allowed to the API, only to the implementation.
pt_BR: Nenhuma alteração é permitida à API, apenas para a implementação.

note: (itstool) path: section/p
en: Typically, projects commit to backwards-compatibility when they say an API is ‘stable’. Very few projects commit to total stability because it would prevent almost all further development of the project.
pt_BR: Geralmente, projetos se comprometem com compatibilidade reversa quando eles dizem que uma API é ‘estável’. Muito poucos projetos se comprometem à total estabilidade por impediria quase que todos os desenvolvimentos posteriores do projeto.

note: (itstool) path: section/title (itstool) path: page/title
en: Versioning
pt_BR: Versionamento

note: (itstool) path: section/p
en: API stability guarantees are strongly linked to project versioning; both package versioning and libtool versioning. Libtool versioning exists entirely for the purpose of tracking ABI stability, and is explained in detail on the <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> or <link xref="versioning"/>.
pt_BR: Garantias de estabilidade de API estão fortemente vinculadas a versionamento do projeto; tanto versionamento de pacote e versionamento do libtool. Versionamento do libtool existe totalmente para o propósito de rastrear a estabilidade da ABI e é explicado em detalhes em <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> (Caçador de mitos de autotools) ou <link xref="versioning"/>.

note: (itstool) path: section/p
en: Package versioning (<em>major.minor.micro</em>) is strongly linked to API stability: typically, the major version number is incremented when backwards-incompatible changes are made (for example, when functions are renamed, parameters are changed, or functions are removed). The minor version number is incremented when forwards-incompatible changes are made (for example, when new public API is added). The micro version number is incremented when code changes are made without modifying API. See <link xref="versioning"/> for more information.
pt_BR: Versionamento de pacote (<em>maior.menor.micro</em>) está fortemente vinculado à estabilidade da API: geralmente, o número da versão maior é incrementado quando alterações incompatíveis com versões anteriores são feitas (por exemplo, quando funções são renomeadas, parâmetros são alterados, ou funções são removidas). O número da versão menor é incrementada quando alterações incompatíveis com versões posteriores são feitas (por exemplo, quando uma nova API pública é adicionada). O número da versão micro é incrementada quando as alterações no código são feitas sem modificar a API. Veja <link xref="versioning"/> para mais informações.

note: (itstool) path: section/p
en: API versioning is just as important for D-Bus APIs and GSettings schemas (if they are likely to change) as for C APIs. See the <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">documentation on D-Bus API versioning</link> for details.
pt_BR: Versionamento de API é tão importante para APIs de D-Bus e esquemas de GSettings (se eles são suscetíveis de alterações) quanto é para APIs C. Veja a <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">documentação sobre versionamento de API de D-Bus</link> para detalhes.

note: (itstool) path: section/p
en: For GIR APIs, their stability typically follows the C API stability, as they are generated from the C API. One complexity is that their stability additionally depends on the version of gobject-introspection used in generating the GIR, but recent versions have not changed much so this is not a major concern.
pt_BR: Para APIs GIR, sua estabilidade geralmente segue a estabilidade da API C, como elas são geradas a partir da API C. Uma complexidade é que sua estabilidade depende adicionalmente na versão do gobject-introspection usada na geração do GIR, mas versões recentes não foram muito alteradas, de forma que isso não é uma grande preocupação.

note: (itstool) path: section/title
en: External Links
pt_BR: Links externos

note: (itstool) path: section/p
en: The topic of API stability is covered in the following articles:
pt_BR: O tópico de estabilidade de API é coberto nos seguintes artigos (em inglês):

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Application_programming_interface">Wikipedia page on APIs</link>
pt_BR: <link href="http://en.wikipedia.org/wiki/Application_programming_interface">Página do Wikipédia sobre APIs</link>

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Application_binary_interface">Wikipedia page on ABIs</link>
pt_BR: <link href="http://en.wikipedia.org/wiki/Application_binary_interface">Página do Wikipédia sobre ABIs</link>

note: (itstool) path: item/p
en: <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API versioning documentation</link>
pt_BR: <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Documentação de versionamento de API D-Bus</link>

note: (itstool) path: credit/name
en: The GTK+ Team
pt_BR: A equipe do GTK+

note: (itstool) path: info/desc
en: Our guidelines for C code in GNOME
pt_BR: Nossas diretrizes para código C no GNOME

note: (itstool) path: page/title
en: C Coding Style
pt_BR: Estilo de codificação C

note: (itstool) path: page/p
en: This document presents the preferred coding style for C programs in GNOME. While coding style is very much a matter of taste, in GNOME we favor a coding style that promotes consistency, readability, and maintainability.
pt_BR: Esse documento apresenta o estilo de codificação preferido para programas C no GNOME. Enquanto o estilo de codificação é muito uma questão de gosto, no GNOME somos a favor de um estilo de codificação que promove consistência, legibilidade e manutenção.

note: (itstool) path: page/p
en: We present examples of good coding style as well as examples of bad style that is not acceptable in GNOME. Please try to submit patches that conform to GNOME’s coding style; this indicates that you have done your homework to respect the project’s goal of long-term maintainability. Patches with GNOME’s coding style will also be easier to review!
pt_BR: Nós apresentamos exemplos de bom estilo de codificação, bem como exemplos de estilo ruim que não é aceitável no GNOME. Por favor, tente enviar patches que estejam em conformidade com o estilo de codificação do GNOME; isso indica que você fez seu dever de casa para respeitar o objetivo do projeto de manutenção a longo prazo. Patches com o estilo de codificação do GNOME também serão mais fáceis de revisar!

note: (itstool) path: note/p
en: This document is for C code. For other languages, check the <link xref="index">main page</link> of the GNOME Programming Guidelines.
pt_BR: Esse documento é para código C. Para outras linguagens, veja a <link xref="index">página principal</link> das Diretrizes de programação do GNOME.

note: (itstool) path: page/p
en: These guidelines are heavily inspired by GTK’s CODING-STYLE document, the Linux Kernel’s CodingStyle, and the GNU Coding Standards. These are slight variations of each other, with particular modifications for each project’s particular needs and culture, and GNOME’s version is no different.
pt_BR: Essas diretrizes são fortemente inspiradas no documento “CODING-STYLE” do GTK, no “CodingStyle” do Kernel Linux e no “GNU Coding Standards”. Essas são pequenas variações entre si, com modificações particulares para cada culturas e necessidades em particular do projeto, e a versão do GNOME não é diferente.

note: (itstool) path: section/title
en: The Single Most Important Rule
pt_BR: A regra mais importante

note: (itstool) path: section/p
en: The single most important rule when writing code is this: <em>check the surrounding code and try to imitate it</em>.
pt_BR: A regra mais importante quando se está escrevendo código é essa: <em>veja o código ao redor e tente imitá-lo</em>.

note: (itstool) path: section/p
en: As a maintainer it is dismaying to receive a patch that is obviously in a different coding style to the surrounding code. This is disrespectful, like someone tromping into a spotlessly-clean house with muddy shoes.
pt_BR: Como um mantenedor, é assustador receber um patch que obviamente está em um estilo de codificação diferente do código ao redor. Isso é desrespeitoso, como alguém pisando em uma casa impecavelmente limpa com sapatos cheios de lama.

note: (itstool) path: section/p
en: So, whatever this document recommends, if there is already written code and you are patching it, keep its current style consistent even if it is not your favorite style.
pt_BR: Então, independente do que este documenta recomenda, se há código escrito e você está fazendo um patch para ele, mantenha a consistência do seu estilo atual ainda que não seja seu estilo favorito.

note: (itstool) path: section/title
en: Line Width
pt_BR: Largura da linha

note: (itstool) path: section/p
en: Try to use lines of code between 80 and 120 characters long. This amount of text is easy to fit in most monitors with a decent font size. Lines longer than that become hard to read, and they mean that you should probably restructure your code. If you have too many levels of indentation, it means that you should fix your code anyway.
pt_BR: Tente usar linhas de códigos entre 80 e 120 caracteres. Essa quantidade de texto é fácil de ajustar na maioria dos monitores com um tamanho de fonte decente. Linhas maiores que isso se tornam difíceis de ler, e isso pode significar que você provavelmente deveria restruturar seu código. Se você tiver um número grande de níveis de recuo, isso significa que você provavelmente deveria corrigir seu código de qualquer maneira.

note: (itstool) path: section/title
en: Indentation
pt_BR: Recuo

note: (itstool) path: section/p
en: In general there are two preferred indentation styles for code in GNOME.
pt_BR: Em geral, há dois estilos de recuo preferidos para código no GNOME.

note: (itstool) path: item/p
en: Linux Kernel style. Tabs with a length of 8 characters are used for the indentation, with K&amp;R brace placement:
pt_BR: Estilo do Kernel Linux. Tabulações com um comprimento de 8 caracteres são usados para recuo, com colocação de chaves de K&amp;R:

note: (itstool) path: item/p
en: GNU style. Each new level is indented by 2 spaces, braces go on a line by themselves, and they are indented as well.
pt_BR: Estilo GNU. Cada novo nível possui recuo de 2 espaços, aspas vai em uma linha própria e elas também possuem recuo.

note: (itstool) path: section/p
en: Both styles have their pros and cons. The most important things is to <em>be consistent</em> with the surrounding code. For example, the GTK+ library, which is GNOME’s widget toolkit, is written with the GNU style. Nautilus, GNOME’s file manager, is written in Linux kernel style. Both styles are perfectly readable and consistent when you get used to them.
pt_BR: Ambos estilos têm suas vantagens e desvantagens. O mais importante é <em>ser consistente</em> com o código ao redor. Por exemplo, a biblioteca GTK+, que é uma caixa de ferramentas de widgets do GNOME, é escrito com o estilo GNU. Nautilus, o gerenciador de arquivos do GNOME, é escrito no estilo Kernel Linux. Ambos estilos são perfeitamente legíveis e consistentes quando você se acostuma com eles.

note: (itstool) path: section/p
en: Your first feeling when having to study or work on a piece of code that doesn’t have your preferred indentation style may be, how shall we put it, gut-wrenching. You should resist your inclination to reindent everything, or to use an inconsistent style for your patch. Remember the first rule: <em>be consistent</em> and respectful of that code’s customs, and your patches will have a much higher chance of being accepted without a lot of arguing about the right indentation style.
pt_BR: Seu primeiro sentimento ao ter que estudar ou trabalhar em um pedaço de código que não seja seu preferido em estilo de recuo pode ser, como vamos colocá-lo, desconfortável. Você deve resistir sua inclinação em ajustar o recuo de tudo, ou usar um estilo inconsistente para seu patch. Lembre-se da primeira regra: <em>ser consistente</em> e respeitoso com os costumes do código, e seus patches terão uma chance muito mais alta de serem aceitos sem muita argumentação sobre o estilo de recuo correto.

note: (itstool) path: section/title
en: Tab Characters
pt_BR: Caracteres de tabulações

note: (itstool) path: section/p
en: <em>Do not ever change the size of tabs in your editor</em>; leave them as 8 spaces. Changing the size of tabs means that code that you didn’t write yourself will be perpetually misaligned.
pt_BR: <em>Não altere o tamanho dos tabs em seu editor</em>; deixe-os como 8 espaços. Alterar o tamanho dos tabs naquele código que você não escreveu estará perpetuamente desalinhada.

note: (itstool) path: section/p
en: Instead, set the <em>indentation size</em> as appropriate for the code you are editing. When writing in something other than Linux kernel style, you may even want to tell your editor to automatically convert all tabs to 8 spaces, so that there is no ambiguity about the intended amount of space.
pt_BR: Em vez disso, defina o <em>tamanho do recuo</em> conforme apropriado para o código que você está editando. Quando se está escrevendo em algo diferente do estilo Kernel Linux, você pode está querer dizer ao seu editor para converter todas os tabs para 8 espaços, de forma que não haja ambiguidade sobre a quantidade de espaços.

note: (itstool) path: section/title
en: Braces
pt_BR: Chaves

note: (itstool) path: section/p
en: Curly braces should not be used for single statement blocks:
pt_BR: Chaves não devem ser usadas para blocos de instrução singular:

note: (itstool) path: section/code
en: 
    /* valid */
    if (condition)
    	single_statement ();
    else
    	another_single_statement (arg1);
pt_BR: 
    /* válido */
    if (condição)
    	single_statement ();
    else
    	another_single_statement (arg1);

note: (itstool) path: section/p
en: The “no block for single statements” rule has only four exceptions:
pt_BR: A regra de “nenhum bloco para instruções singulares” possui apenas quatro exceções:

note: (itstool) path: item/p
en: In GNU style, if either side of an if-else statement has braces, both sides should, to match up indentation:
pt_BR: No estilo GNU, se qualquer um dos lados de uma instrução if-else possui chaves, ambos lados deveriam ter, para corresponder o recuo:

note: (itstool) path: item/code
en: 
    /* valid GNU style */
    if (condition)
      {
        foo ();
        bar ();
      }
    else
      {
        baz ();
      }
pt_BR: 
    /* estilo GNU válido */
    if (condição)
      {
        foo ();
        bar ();
      }
    else
      {
        baz ();
      }

note: (itstool) path: item/code
en: 
    /* invalid */
    if (condition)
      {
        foo ();
        bar ();
      }
    else
      baz ();
pt_BR: 
    /* inválido */
    if (condição)
      {
        foo ();
        bar ();
      }
    else
      baz ();

note: (itstool) path: item/p
en: If the single statement covers multiple lines, e.g. for functions with many arguments, and it is followed by <code>else</code> or <code>else if</code>:
pt_BR: Se a instrução singular cobre múltiplas linhas (ex.: para funções com muitos argumentos) e é seguido por <code>else</code> ou <code>eles if</code>:

note: (itstool) path: item/code
en: 
    /* valid Linux kernel style */
    if (condition) {
    	a_single_statement_with_many_arguments (some_lengthy_argument,
    						another_lengthy_argument,
    						and_another_one,
    						plus_one);
    } else
    	another_single_statement (arg1, arg2);
    
    /* valid GNU style */
    if (condition)
      {
        a_single_statement_with_many_arguments (some_lengthy_argument,
                                                another_lengthy_argument,
                                                and_another_one,
                                                plus_one);
      }
    else
      {
        another_single_statement (arg1, arg2);
      }
pt_BR: 
    /* estilo Kernel Linux válido */
    if (condição) {
    	uma_instrução_singular_com_muitos_args (algum_argumento_comprido,
    						outro_argumento_comprido,
    						e_mais_um_outro,
    						mais_um);
    } else
    	outro_arg_singular (arg1, arg2);
    
    /* estilo GNU válido */
    if (condição)
      {
        uma_instrução_singular_com_muitos_args (algum_argumento_comprido,
                                                outro_argumento_comprido,
                                                e_mais_um_outro,
                                                mais_um);
      }
    else
      {
        outro_arg_singular (arg1, arg2);
      }

note: (itstool) path: item/p
en: If the condition is composed of many lines:
pt_BR: Se a condição for composta de muitas linhas:

note: (itstool) path: item/code
en: 
    /* valid Linux kernel style */
    if (condition1 ||
        (condition2 &amp;&amp; condition3) ||
        condition4 ||
        (condition5 &amp;&amp; (condition6 || condition7))) {
    	a_single_statement ();
    }
    
    /* valid GNU style */
    if (condition1 ||
        (condition2 &amp;&amp; condition3) ||
        condition4 ||
        (condition5 &amp;&amp; (condition6 || condition7)))
      {
        a_single_statement ();
      }
pt_BR: 
    /* estilo Kernel Linux válido */
    if (condição1 ||
        (condição2 &amp;&amp; condição3) ||
        condição4 ||
        (condição5 &amp;&amp; (condição6 || condição7))) {
    	uma_instrução_singular ();
    }
    
    /* estilo GNU válido */
    if (condição1 ||
        (condição2 &amp;&amp; condição3) ||
        condição4 ||
        (condição5 &amp;&amp; (condição6 || condição7)))
      {
        uma_instrução_singular ();
      }

note: (itstool) path: item/p
en: Note that such long conditions are usually hard to understand. A good practice is to set the condition to a boolean variable, with a good name for that variable. Another way is to move the long condition to a function.
pt_BR: Note que tais condições longas são geralmente difíceis de entender. Uma boa prática é definir essa condição para uma variável booleana, com um bom nome para aquela variável. Uma outra forma é mover a condição longa para uma função.

note: (itstool) path: item/p
en: Nested <code>if</code>s, in which case the block should be placed on the outermost <code>if</code>:
pt_BR: <code>if</code>s aninhados, caso em que o bloco deve ser colocado <code>if</code> mais extremo:

note: (itstool) path: item/code
en: 
    /* valid Linux kernel style */
    if (condition) {
    	if (another_condition)
    		single_statement ();
    	else
    		another_single_statement ();
    }
    
    /* valid GNU style */
    if (condition)
      {
        if (another_condition)
          single_statement ();
        else
          another_single_statement ();
      }
pt_BR: 
    /* estilo Kernel Linux válido */
    if (condição) {
    	if (outra_condição)
    		instrução_singular ();
    	else
    		outra_instrução_singular ();
    }
    
    /* estilo GNU válido */
    if (condição)
      {
        if (outra_condição)
          instrução_singular ();
        else
          outra_instrução_singular ();
      }

note: (itstool) path: item/code
en: 
    /* invalid */
    if (condition)
    	if (another_condition)
    		single_statement ();
    	else if (yet_another_condition)
    		another_single_statement ();
pt_BR: 
    /* inválido */
    if (condição)
    	if (outra_condição)
    		instrução_singular ();
    	else if (mais_uma_condição)
    		outra_instrução_singular ();

note: (itstool) path: section/p
en: In general, new blocks should be placed on a new indentation level, like this:
pt_BR: Em geral, novos blocos devem ser colocados em um novo nível de recuo, como este:

note: (itstool) path: section/code
en: 
    int retval = 0;
    
    statement_1 ();
    statement_2 ();
    
    {
    	int var1 = 42;
    	gboolean res = FALSE;
    
    	res = statement_3 (var1);
    
    	retval = res ? -1 : 1;
    }
pt_BR: 
    int retval = 0;
    
    instrucao_1 ();
    instrucao_2 ();
    
    {
    	int var1 = 42;
    	gboolean res = FALSE;
    
    	res = instrucao_3 (var1);
    
    	retval = res ? -1 : 1;
    }

note: (itstool) path: section/p
en: While curly braces for function definitions should rest on a new line they should not add an indentation level:
pt_BR: Enquanto chaves para definições de função devem ficar em uma nova linha, elas não devem adicionar um novo nível de recuo:

note: (itstool) path: section/code
en: 
    /* valid Linux kernel style*/
    static void
    my_function (int argument)
    {
    	do_my_things ();
    }
    
    /* valid GNU style*/
    static void
    my_function (int argument)
    {
      do_my_things ();
    }
pt_BR: 
    /* estilo Kernel Linux válido */
    static void
    minha_funcao (int argumento)
    {
    	faz_minhas_coisas ();
    }
    
    /* estilo GNU válido */
    static void
    minha_funcao (int argumento)
    {
      faz_minhas_coisas ();
    }

note: (itstool) path: section/code
en: 
    /* invalid */
    static void
    my_function (int argument) {
    	do_my_things ();
    }
    
    /* invalid */
    static void
    my_function (int argument)
      {
        do_my_things ();
      }
pt_BR: 
    /* inválido */
    static void
    minha_funcao (int argumento) {
    	faz_minhas_coisas ();
    }
    
    /* inválido */
    static void
    minha_funcao (int argumento)
      {
        faz_minhas_coisas ();
      }

note: (itstool) path: section/title
en: Conditions
pt_BR: Condições

note: (itstool) path: section/p
en: Do not check boolean values for equality. By using implicit comparisons, the resulting code can be read more like conversational English. Another rationale is that a ‘true’ value may not be necessarily equal to whatever the <code>TRUE</code> macro uses. For example:
pt_BR: Não verifique valores booleanos por igualdade. Ao usar comparações implícitas, o código resultante pode ser mais parecido com o inglês conversacional. Um outro fundamento é que um valor ‘verdadeiro’ não necessariamente será igual a macro <code>TRUE</code> usada. Por exemplo:

note: (itstool) path: section/code
en: 
    /* invalid */
    if (found == TRUE)
    	do_foo ();
    
    /* invalid */
    if (found == FALSE)
    	do_bar ();
pt_BR: 
    /* inválido */
    if (localizado == TRUE)
    	fazer_foo ();
    
    /* inválido */
    if (localizado == FALSE)
    	fazer_bar ();

note: (itstool) path: section/code
en: 
    /* valid */
    if (found)
    	do_foo ();
    
    /* valid */
    if (!found)
    	do_bar ();
pt_BR: 
    /* válido */
    if (localizado)
    	fazer_foo ();
    
    /* válido */
    if (!localizado)
    	fazer_bar ();

note: (itstool) path: section/p
en: The C language uses the value 0 for many purposes. As a numeric value, the end of a string, a null pointer and the <code>FALSE</code> boolean. To make the code clearer, you should write code that highlights the specific way 0 is used. So when reading a comparison, it is possible to know the variable type. For boolean variables, an implicit comparison is appropriate because it’s already a logical expression. Other variable types are not logical expressions by themselves, so an explicit comparison is better:
pt_BR: A linguagem C usa o valor 0 para muitos propósitos. Como um valor numérico, o fim de uma string, um ponteiro nulo e o booleano <code>FALSE</code>. Para tornar o código mais limpo, você deveria escrever código que realça a forma específica que 0 é usado. Então, ao ler uma comparação, é possível saber o tipo de variável.  Para variáveis booleanas, uma comparação implícita é apropriado porque já é uma expressão lógica. Outros tipos de variáveis que não são expressões lógicas por si só, então uma comparação explícita é melhor:

note: (itstool) path: section/code
en: 
    /* valid */
    if (some_pointer == NULL)
    	do_blah ();
    
    /* valid */
    if (number == 0)
    	do_foo ();
    
    /* valid */
    if (str != NULL &amp;&amp; *str != '\0')
    	do_bar ();
pt_BR: 
    /* válido */
    if (algum_ponteiro == NULL)
    	fazer_blá ();
    
    /* válido */
    if (número == 0)
    	fazer_foo ();
    
    /* válido */
    if (str != NULL &amp;&amp; *str != '\0')
    	fazer_bar ();

note: (itstool) path: section/code
en: 
    /* invalid */
    if (!some_pointer)
    	do_blah ();
    
    /* invalid */
    if (!number)
    	do_foo ();
    
    /* invalid */
    if (str &amp;&amp; *str)
    	do_bar ();
pt_BR: 
    /* inválido */
    if (!algum_ponteiro)
    	fazer_blá ();
    
    /* inválido */
    if (!número)
    	fazer_foo ();
    
    /* inválido */
    if (str &amp;&amp; *str)
    	fazer_bar ();

note: (itstool) path: section/title
en: Functions
pt_BR: Funções

note: (itstool) path: section/p
en: Functions should be declared by placing the returned value on a separate line from the function name:
pt_BR: Funções devem ser declaradas colocando o valor de retorno em uma linha separada do nome da função:

note: (itstool) path: section/code
en: 
    void
    my_function (void)
    {
      …
    }
pt_BR: 
    void
    minha_funcao (void)
    {
      …
    }

note: (itstool) path: section/p
en: The argument list must be broken into a new line for each argument, with the argument names right aligned, taking into account pointers:
pt_BR: A lista de argumentos deve estar quebrada em nova linha para cada argumento, com os nomes dos argumentos alinhados à direita, levando em consideração os ponteiros:

note: (itstool) path: section/code
en: 
    void
    my_function (some_type_t      type,
                 another_type_t  *a_pointer,
                 double_ptr_t   **double_pointer,
                 final_type_t     another_type)
    {
      …
    }
pt_BR: 
    void
    minha_funcao (algum_tipo_t    tipo,
                  outro_tipo_t   *um_ponteiro,
                  double_ptr_t  **ponteiro_duplo,
                  tipo_final_t    outro_tipo)
    {
      …
    }

note: (itstool) path: section/p
en: If you use Emacs, you can use <code>M-x align</code> to do this kind of alignment automatically. Just put the point and mark around the function’s prototype, and invoke that command.
pt_BR: Se você usa Emacs, você pode usar <code>M-x align</code> para fazer esse tipo de alinhamento automaticamente. Basca colocar o ponteiro e marcar em volta do protótipo da função e invocar aquele comando.

note: (itstool) path: section/p
en: The alignment also holds when invoking a function without breaking the line length limit:
pt_BR: O alinhamento também se mantém ao invocar uma função sem quebrar o limite de comprimento da linha:

note: (itstool) path: section/code
en: 
    align_function_arguments (first_argument,
                              second_argument,
                              third_argument);
pt_BR: 
    alinha_args_de_funcoes (primeiro_argumento,
                            segundo_argumento,
                            terceiro_argumento);

note: (itstool) path: section/title
en: Whitespace
pt_BR: Espaço em branco

note: (itstool) path: section/p
en: Always put a space before an opening parenthesis but never after:
pt_BR: Sempre coloque espaço antes de abrir parênteses, mas nunca após:

note: (itstool) path: section/code
en: 
    /* valid */
    if (condition)
    	do_my_things ();
    
    /* valid */
    switch (condition) {
    }
pt_BR: 
    /* válido */
    if (condição)
    	faz_minhas_coisas ();
    
    /* válido */
    switch (condição) {
    }

note: (itstool) path: section/code
en: 
    /* invalid */
    if(condition)
    	do_my_things();
    
    /* invalid */
    if ( condition )
    	do_my_things ( );
pt_BR: 
    /* inválido */
    if(condição)
    	faz_minhas_coisas();
    
    /* inválido */
    if ( condição )
    	faz_minhas_coisas ( );

note: (itstool) path: section/p
en: When declaring a structure type use newlines to separate logical sections of the structure:
pt_BR: Ao declarar um tipo de estrutura, use novas linhas para separar seções lógicas da estrutura:

note: (itstool) path: section/p
en: Do not eliminate whitespace and newlines just because something would fit on a single line:
pt_BR: Não elimine espaços em branco e novas linhas apenas por que alguma coisa caberia em uma única linha:

note: (itstool) path: section/code
en: 
    /* invalid */
    if (condition) foo (); else bar ();
pt_BR: 
    /* inválido */
    if (condição) foo (); else bar ();

note: (itstool) path: section/p
en: Do eliminate trailing whitespace on any line, preferably as a separate patch or commit. Never use empty lines at the beginning or at the end of a file.
pt_BR: Elimine espaços em branco de qualquer linha, preferivelmente como um patch ou commit separado. Nunca use linhas vazias no começo ou no fim de um arquivo.

note: (itstool) path: section/p
en: This is a little Emacs function that you can use to clean up lines with trailing whitespace:
pt_BR: Essa é uma pequena função de Emacs que você pode usar para limpar linhas terminando com espaço em branco:

note: (itstool) path: section/code
en: 
    (defun clean-line-ends ()
      (interactive)
      (if (not buffer-read-only)
          (save-excursion
    	(goto-char (point-min))
    	(let ((count 0))
    	  (while (re-search-forward "[ 	]+$" nil t)
    	    (setq count (+ count 1))
    	    (replace-match "" t t))
    	  (message "Cleaned %d lines" count)))))
pt_BR: 
    (defun clean-line-ends ()
      (interactive)
      (if (not buffer-read-only)
          (save-excursion
    	(goto-char (point-min))
    	(let ((count 0))
    	  (while (re-search-forward "[ 	]+$" nil t)
    	    (setq count (+ count 1))
    	    (replace-match "" t t))
    	  (message "Limpadas %d linhas" count)))))

note: (itstool) path: section/title
en: The <code>switch</code> Statement
pt_BR: A instrução <code>switch</code>

note: (itstool) path: section/p
en: A <code>switch</code> should open a block on a new indentation level, and each <code>case</code> should start on the same indentation level as the curly braces, with the case block on a new indentation level:
pt_BR: Um <code>switch</code> deve abrir um bloco em um novo nível de recuo, e cada <code>case</code> deve iniciar no mesmo nível de recuo que as chaves, com o bloco de <code>case</code> em um novo nível de recuo:

note: (itstool) path: section/code
en: 
    /* valid Linux kernel style */
    switch (condition) {
    case FOO:
    	do_foo ();
    	break;
    
    case BAR:
    	do_bar ();
    	break;
    }
    
    /* valid GNU style */
    switch (condition)
      {
      case FOO:
        do_foo ();
        break;
    
      case BAR:
        do_bar ();
        break;
      }
pt_BR: 
    /* estilo Kernel Linux válido */
    switch (condição) {
    case FOO:
    	fazer_foo ();
    	break;
    
    case BAR:
    	fazer_bar ();
    	break;
    }
    
    /* estilo GNU válido */
    switch (condição)
      {
      case FOO:
        fazer_foo ();
        break;
    
      case BAR:
        fazer_bar ();
        break;
      }

note: (itstool) path: section/code
en: 
    /* invalid */
    switch (condition) {
      case FOO: do_foo (); break;
      case BAR: do_bar (); break;
    }
    
    /* invalid */
    switch (condition)
      {
      case FOO: do_foo ();
        break;
      case BAR: do_bar ();
        break;
      }
    
    /* invalid */
    switch (condition)
      {
        case FOO:
        do_foo ();
        break;
        case BAR:
        do_bar ();
        break;
      }
pt_BR: 
    /* inválido */
    switch (condição) {
      case FOO: fazer_foo (); break;
      case BAR: fazer_bar (); break;
    }
    
    /* inválido */
    switch (condição)
      {
      case FOO: fazer_foo ();
        break;
      case BAR: fazer_bar ();
        break;
      }
    
    /* inválido */
    switch (condição)
      {
        case FOO:
        fazer_foo ();
        break;
        case BAR:
        fazer_bar ();
        break;
      }

note: (itstool) path: section/p
en: It is preferable, though not mandatory, to separate the various cases with a newline:
pt_BR: É preferível, apesar de não ser obrigatório, separar os vários cases com uma nova linha:

note: (itstool) path: section/code
en: 
    switch (condition) {
    case FOO:
    	do_foo ();
    	break;
    
    case BAR:
    	do_bar ();
    	break;
    
    default:
    	do_default ();
    }
pt_BR: 
    switch (condição) {
    case FOO:
    	fazer_foo ();
    	break;
    
    case BAR:
    	fazer_foo ();
    	break;
    
    default:
    	fazer_padrão ();
    }

note: (itstool) path: section/p
en: The <code>break</code> statement for the <code>default</code> case is not mandatory.
pt_BR: A instrução <code>break</code> para o caso <code>default</code> não é obrigatório.

note: (itstool) path: section/p
en: If switching over an enumerated type, a <code>case</code> statement must exist for every member of the enumerated type. For members you do not want to handle, alias their <code>case</code> statements to <code>default</code>:
pt_BR: Se alternando sobre um tipo enumerado, uma instrução <code>case</code> deve existir para cada novo membro do tipo enumerado. Para membros que você não deseja tratar, apelide suas instruções <code>case</code> para <code>default</code>:

note: (itstool) path: section/code
en: 
    switch (enumerated_condition) {
    case HANDLED_1:
    	do_foo ();
    	break;
    
    case HANDLED_2:
    	do_bar ();
    	break;
    
    case IGNORED_1:
    case IGNORED_2:
    default:
    	do_default ();
    }
pt_BR: 
    switch (condição_enumerada) {
    case TRATADA_1:
    	fazer_foo ();
    	break;
    
    case TRATADA_2:
    	fazer_bar ();
    	break;
    
    case IGNORADA_1:
    case IGNORADA_2:
    default:
    	fazer_padrão ();
    }

note: (itstool) path: section/p
en: If most members of the enumerated type should not be handled, consider using an <code>if</code> statement instead of a <code>switch</code>.
pt_BR: Se a maioria dos membros do tipo enumerado não deve ser tratada, considere usar uma instrução <code>if</code> em vez de um <code>switch</code>.

note: (itstool) path: section/p
en: If a <code>case</code> block needs to declare new variables, the same rules as the inner blocks apply (see above); the <code>break</code> statement should be placed outside of the inner block:
pt_BR: Se um bloco <code>case</code> precisa declarar novas variáveis, as mesmas regras que os blocos internos se aplicam (veja acima); a instrução <code>break</code> deve ser colocada fora do bloco interno:

note: (itstool) path: section/code
en: 
    /* valid GNU style */
    switch (condition)
      {
      case FOO:
        {
          int foo;
    
          foo = do_foo ();
        }
        break;
    
      …
      }
pt_BR: 
    /* estilo GNU válido */
    switch (condição)
      {
      case FOO:
        {
          int foo;
    
          foo = fazer_foo ();
        }
        break;
    
      …
      }

note: (itstool) path: section/title
en: Header Files
pt_BR: Arquivos de cabeçalho

note: (itstool) path: section/p
en: The only major rule for headers is that the function definitions should be vertically aligned in three columns:
pt_BR: A única regra importante para cabeçalhos é que as definições de funções devem estar alinhados verticalmente em três colunas:

note: (itstool) path: section/code
en: 
    return_type          function_name           (type   argument,
                                                  type   argument,
                                                  type   argument);
pt_BR: 
    tipo_retorno          nome_funcao            (tipo   argumento,
                                                  tipo   argumento,
                                                  tipo   argumento);

note: (itstool) path: section/p
en: The maximum width of each column is given by the longest element in the column:
pt_BR: A largura máxima de cada coluna é dada pelo elemento mais longo na coluna:

note: (itstool) path: section/p
en: It is also possible to align the columns to the next tab:
pt_BR: Também é possível alinhar as colunas à próxima tabulação:

note: (itstool) path: section/p
en: As before, you can use <code>M-x align</code> in Emacs to do this automatically.
pt_BR: Como anteriormente, você pode usar <code>M-x align</code> no Emacs para fazer isso automaticamente.

note: (itstool) path: section/p
en: If you are creating a public library, try to export a single public header file that in turn includes all the smaller header files into it. This is so that public headers are never included directly; rather a single include is used in applications. For example, GTK+ uses the following in its header files that should not be included directly by applications:
pt_BR: Se você está criando uma biblioteca pública, tente exportar um único arquivo de cabeçalho público que, por sua vez, inclua todos os arquivos de cabeçalhos menores nele. Isto é para que cabeçalhos públicos nunca seja incluídos diretamente; em vez disso, uma única inclusão é usada nos aplicativos. Por exemplo, GTK+ usa o seguinte em seus arquivos de cabeçalhos que não devem ser incluídos diretamente por aplicativos:

note: (itstool) path: section/p
en: For libraries, all headers should have inclusion guards (for internal usage) and C++ guards. These provide the <code>extern "C"</code> magic that C++ requires to include plain C headers:
pt_BR: Para bibliotecas, todos cabeçalhos devem ter proteções de inclusão (para uso interno) e proteções de C++ ou, em inglês, <em>#include guards</em> e <em>C++ guards</em>. Estas fornece a mágica <code>extern "C"</code> que C++ requer para incluir cabeçalhos de C simples:

note: (itstool) path: section/title
en: GObject Classes
pt_BR: Classes de GObject

note: (itstool) path: section/p
en: GObject class definitions and implementations require some additional coding style notices, and should always be <link xref="namespacing#gobject">correctly namespaced</link>.
pt_BR: Definições e implementações de classe GObject exigem algumas notas adicionais de estilo de codificação, e devem sempre estar sob <link xref="namespacing#gobject">espaço de nome correto</link>.

note: (itstool) path: section/p
en: Typedef declarations should be placed at the beginning of the file:
pt_BR: Declarações <code>Typedef</code> devem ser colocadas no começo do arquivo:

note: (itstool) path: section/p
en: This includes enumeration types:
pt_BR: Isso inclui tipos de enumeração:

note: (itstool) path: section/p
en: And callback types:
pt_BR: A tipos de retorno de chamada (<em>callback</em>):

note: (itstool) path: section/p
en: Instance structures should be declared using <code>G_DECLARE_FINAL_TYPE</code> or <code>G_DECLARE_DERIVABLE_TYPE</code>:
pt_BR: Estruturas de instâncias devem ser declaradas usando <code>G_DECLARE_FINAL_TYPE</code> ou <code>G_DECLARE_DERIVABLE_TYPE</code>:

note: (itstool) path: section/p
en: For final types, private data can be stored in the object struct, which should be defined in the C file:
pt_BR: Para tipos finais, dados privados podem ser armazenados em um objeto <code>struct</code>, o qual deve ser definido no arquivo C:

note: (itstool) path: section/code
en: 
    struct _GtkFoo
    {
      GObject   parent_instance;
    
      guint     private_data;
      gpointer  more_private_data;
    };
pt_BR: 
    struct _GtkFoo
    {
      GObject   instancia_pai;
    
      guint     dados_privados;
      gpointer  mais_dados_privados;
    };

note: (itstool) path: section/p
en: For derivable types, private data must be stored in a private struct in the C file, configured using <code>G_DEFINE_TYPE_WITH_PRIVATE()</code> and accessed using a <code>_get_instance_private()</code> function:
pt_BR: Para tipos deriváveis, dados privados devem estar armazenados em um struct privado no arquivo C, configurado usando <code>G_DEFINE_TYPE_WITH_PRIVATE()</code> e acessado usando uma função <code>_get_instance_private()</code>:

note: (itstool) path: section/p
en: Always use the <code>G_DEFINE_TYPE()</code>, <code>G_DEFINE_TYPE_WITH_PRIVATE()</code>, and <code>G_DEFINE_TYPE_WITH_CODE()</code> macros, or their abstract variants <code>G_DEFINE_ABSTRACT_TYPE()</code>, <code>G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE()</code>, and <code>G_DEFINE_ABSTRACT_TYPE_WITH_CODE()</code>; also, use the similar macros for defining interfaces and boxed types.
pt_BR: Sempre use as macros <code>G_DEFINE_TYPE()</code>, <code>G_DEFINE_TYPE_WITH_PRIVATE()</code> e <code>G_DEFINE_TYPE_WITH_CODE()</code> ou suas variantes abstratas <code>G_DEFINE_ABSTRACT_TYPE()</code>, <code>G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE()</code> e <code>G_DEFINE_ABSTRACT_TYPE_WITH_CODE()</code>; também, use as macros similares para definir interfaces e tipos “boxed”.

note: (itstool) path: section/p
en: Interface types should always have the dummy typedef for cast purposes:
pt_BR: Tipos de interfaces devem sempre ter um typedef dummy visando as chamadas:

note: (itstool) path: section/p
en: The interface structure should have ‘Interface’ postfixed to the dummy typedef:
pt_BR: A estrutura da interface deve ter ‘Interface’ pós-fixado ao typedef dummy:

note: (itstool) path: section/p
en: Interfaces must have the following macros:
pt_BR: Interfaces devem ter as seguintes macros:

note: (itstool) path: td/p
en: Expands to
pt_BR: Expande para

note: (itstool) path: section/title
en: Memory Allocation
pt_BR: Alocação de memória

note: (itstool) path: section/p
en: When dynamically allocating data on the heap use <code>g_new()</code>.
pt_BR: Quando se estiver alocando dados em uma pilha, use <code>g_new()</code>.

note: (itstool) path: section/p
en: Public structure types should always be returned after being zero-ed, either explicitly for each member, or by using <code>g_new0()</code>.
pt_BR: Tipos de estrutura pública devem sempre ser retornados após serem zerados, seja explicitamente para cada membro, seja usando <code>g_new0()</code>.

note: (itstool) path: section/p
en: See <link xref="memory-management"/> for more details.
pt_BR: Veja <link xref="memory-management"/> para mais detalhes.

note: (itstool) path: section/p
en: Try to avoid private macros unless strictly necessary. Remember to <code>#undef</code> them at the end of a block or a series of functions needing them.
pt_BR: Tente evitar macros privadas, a menos que seja estritamente necessário. Lembre-se de usar <code>#undef</code> nelas no final de um bloco ou uma série de funções que precisem delas.

note: (itstool) path: section/p
en: Inline functions are usually preferable to private macros.
pt_BR: Funções em linha são geralmente preferíveis a macros privadas.

note: (itstool) path: section/p
en: Public macros should not be used unless they evaluate to a constant.
pt_BR: Macros públicas não devem ser usadas a menos que elas sejam avaliadas para uma constante.

note: (itstool) path: section/title
en: Public API
pt_BR: API pública

note: (itstool) path: section/p
en: Avoid exporting variables as public API, since this is cumbersome on some platforms. It is always preferable to add getters and setters instead. Also, beware global variables in general.
pt_BR: Evite exportar variáveis como API pública, já que isso pode ser pesado demais para algumas plataformas. Em vez disso, é sempre preferível adicionar “gets” e “sets”. Também, cuidado com variáveis globais em geral.

note: (itstool) path: section/title
en: Private API
pt_BR: API privada

note: (itstool) path: section/p
en: Non-exported functions that are needed in more than one source file should be prefixed with an underscore (‘_’), and declared in a private header file. For example, <code>_mylib_internal_foo()</code>.
pt_BR: Funções não exportadas que são necessárias em mais de um arquivo fonte devem ser prefixadas com um sublinhado (‘_’) e declarados em um arquivo de cabeçalho privado. Por exemplo, <code>_minhalib_foo_interno()</code>.

note: (itstool) path: section/p
en: Underscore-prefixed functions are never exported.
pt_BR: Funções prefixadas com sublinhado nunca são exportadas.

note: (itstool) path: section/p
en: Non-exported functions that are only needed in one source file should be declared static.
pt_BR: Funções não exportadas que são necessárias apenas em um arquivo fonte devem ser declaradas com estáticas.

note: (itstool) path: p/link
en: Creative Commons Attribution-Share Alike 3.0 United States License
pt_BR: Licença Creative Commons Atribuição-Compartilhada Igual 3.0, dos Estados Unidos

note: (itstool) path: license/p
en: This work is licensed under a <_:link-1/>.
pt_BR: Este trabalho está licenciado sob uma <_:link-1/>.

note: (itstool) path: license/p
en: As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.
pt_BR: Como uma exceção especial, os detentores do copyright dão a você permissão para copiar, modificar e distribuir o código exemplo contido nesta documentação sob os termos de sua escolha, sem restrição.

note: (itstool) path: info/desc
en: Simple persistent object stores
pt_BR: Armazenamentos simples de objetos persistentes

note: (itstool) path: page/title
en: Databases
pt_BR: Bancos de dados

note: (itstool) path: item/p
en: Use databases for appropriate use cases: not configuration data (use GSettings). (<link xref="#when-to-use-databases"/>)
pt_BR: Use bancos de dados para casos de uso apropriados: não para dados de configuração (use GSettings). (<link xref="#when-to-use-databases"/>)

note: (itstool) path: item/p
en: Choose between GOM and GVDB based on whether indexing is required. (<link xref="#when-to-use-databases"/>)
pt_BR: Escolha entre GOM e GVDB com base em se indexação é necessária. (<link xref="#when-to-use-databases"/>)

note: (itstool) path: item/p
en: Consider your vacuuming policy before committing to using GOM. (<link xref="#when-to-use-databases"/>)
pt_BR: Considere sua política de <em>vacuuming</em> antes de usar GOM. (<link xref="#when-to-use-databases"/>)

note: (itstool) path: item/p
en: Avoid SQL injection vulnerabilities by using prepared statements. (<link xref="#sql-injection"/>)
pt_BR: Evite vulnerabilidades de injeção SQL usando as instruções preparadas. (<link xref="#sql-injection"/>)

note: (itstool) path: section/title
en: When to Use Databases
pt_BR: Quando usar bancos de dados

note: (itstool) path: section/p
en: Configuration data should be stored in <link href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>. As a rule of thumb, if some data needs to be persistent and affects how an application behaves, it is configuration data. If it could potentially be subject to policies imposed by the system administrator (such as proxy or lockdown settings), it is configuration data. If it contains user created content, it is not configuration data, and should not be stored in GSettings.
pt_BR: Dados de configuração devem ser armazenados em <link href="https://developer.gnome.org/gio/stable/GSettings.html">GSettings</link>. Como uma regra de ouro, se alguns dados precisam ser persistentes e afetam como um aplicativo se comporta, eles são dados de configuração. Se eles estão potencialmente sujeitos a políticas impostas pelo administrador do sistema (tal como configurações de proxy e bloqueio), são dados de configuração. Se eles contêm conteúdo criado por usuários, não são dados de configuração e não devem ser armazenados em GSettings.

note: (itstool) path: section/p
en: For such situations where user data is highly structured, storing it in a database is sensible. There are two main databases suggested for use within GNOME: GOM and GVDB. GOM is a wrapper around SQLite, and hence implements indexing of fields and SQL-style queries. GVDB is a much simpler object store, supporting fast serialization of a dictionary of objects to disk.
pt_BR: Para tais situações nas quais dados de usuário estejam altamente estruturado, armazená-los em um banco de dados é sensível. Há dois bancos de dados principais sugeridos para usar com GNOME: GOM e GVDB. GOM é um interfaceador do SQLite e, portanto, implementa indexação de campos e consultas no tipo SQL. GVDB é um armazenamento de objeto muito mais simples, oferecendo suporte a serialização rápida de um dicionário de objetos para disco.

note: (itstool) path: section/p
en: GOM should be used if you need advanced features, especially indexing. GVDB should be used otherwise.
pt_BR: GOM deve ser usado se você precisa de recursos avançados, especialmente indexação. Do contrário, GVDB deve ser usado.

note: (itstool) path: section/p
en: Before deciding to use GOM (and hence SQLite), you must consider a vacuuming policy for the database, and whether your use case will interact well with SQLite’s vacuuming system. Vacuuming is effectively SQLite’s term for defragmenting the database — if a database is not vacuumed appropriately, performance will degrade and the database size will increase indefinitely. Read <link href="http://blogs.gnome.org/jnelson/2015/01/06/sqlite-vacuum-and-auto_vacuum/">this article</link> on vacuuming for more information; please consider it before choosing to use GOM.
pt_BR: Antes de decidir por usar o GOM (e, portanto, SQLite), você deveria considerar uma política de <em>vacuuming</em> para o banco de dados e se seu caso de uso vai interagir bem com o sistema de vácuo do SQLite. <em>Vaccuming</em> é, efetivamente, o termo para desfragmentação do banco de dados — se um banco de dados não for adequadamente aspirado, o desempenho será degradado e seu tamanho vai aumentar indefinidamente. Leia <link href="http://blogs.gnome.org/jnelson/2015/01/06/sqlite-vacuum-and-auto_vacuum/">este artigo</link> sobre <em>vacuuming</em> para mais informações; considere-o antes de escolher usar GOM.

note: (itstool) path: section/p
en: GNOME has another database library: GNOME Data Access (GDA). This is targeted at abstracting access to various types of relational database, for use in a database utility program or office program, for example. It is not suitable for storing <link href="https://developer.gnome.org/gio/stable/GSettings.html">user settings</link>.
pt_BR: GNOME possui uma outra biblioteca de banco de dados: GNOME Data Access (GDA). Ela visa abstrair o acesso a vários tipos de banco de dados relacionais, para uso em um programa utilitário de banco de dados ou programa de escritório, por exemplo. Ela não é adequado para armazenar <link href="https://developer.gnome.org/gio/stable/GSettings.html">configurações de usuários</link>.

note: (itstool) path: section/title
en: Using GOM
pt_BR: Usando o GOM

note: (itstool) path: section/p
en: Providing a GOM tutorial is beyond the scope of this document, but a <link href="https://developer.gnome.org/gom/">reference manual is available</link>.
pt_BR: Fornecer um tutorial do GOM vai além do escopo deste documento, mas um <link href="https://developer.gnome.org/gom/">manual de referência está disponível</link>.

note: (itstool) path: section/title
en: SQL Injection
pt_BR: Injeção de SQL

note: (itstool) path: section/p
en: GOM does allow access to the lower level SQLite query APIs. When using them, queries <em style="strong">must</em> be constructed using SQLite’s <link href="https://www.sqlite.org/c3ref/stmt.html">prepared statement</link> and <link href="https://www.sqlite.org/c3ref/bind_blob.html">value binding</link> API, rather than by constructing SQL strings then passing them to SQLite to parse. Constructing strings makes <link href="http://en.wikipedia.org/wiki/SQL_injection">SQL injection</link> vulnerabilities very likely, which can give attackers access to arbitrary user data from the database.
pt_BR: GOM não permite acesso às APIs de consulta de baixo de nível do SQLite. Ao usá-las, as consultas <em style="strong">devem</em> ser construídas usando a API de <link href="https://www.sqlite.org/c3ref/stmt.html">prepared statement</link> (instrução preparada) e <link href="https://www.sqlite.org/c3ref/bind_blob.html">value binding</link> (associação de valor) do SQLite, em vez de construir strings SQL e, então, passá-las para o SQLite interpretar. Construir strings possibilita as vulnerabilidades da <link href="https://pt.wikipedia.org/wiki/Inje%C3%A7%C3%A3o_de_SQL">injeção de SQL</link>, o que pode fornecer acesso aos atacantes a dados de usuários a partir do banco de dados.

note: (itstool) path: section/title
en: Using GVDB
pt_BR: Usando o GVDB

note: (itstool) path: section/p
en: GVDB has a simple API which mirrors a conventional hash table. Presently, GVDB is only available as a copy-and-paste library; fetch the most recent copy of the code from <link href="https://git.gnome.org/browse/gvdb">GVDB git</link> and copy it into your project. It is licenced under LGPLv2.1+.
pt_BR: GVDB possui uma API simples que espelha a tabela de hash convencional. Atualmente, GVDB está disponível apenas como uma biblioteca de copiar-e-colar; obtenha a cópia mais recente do código de <link href="https://git.gnome.org/browse/gvdb">GVDB git</link> e copie-o para seu projeto. Ele está licenciado sob LGPLv2.1+.

note: (itstool) path: section/p
en: A full GVDB tutorial is beyond the scope of this document.
pt_BR: Um tutorial completo do GVDB vai além do escopo deste documento.

note: (itstool) path: info/desc
en: Adding documentation to libraries and APIs
pt_BR: Adicionando documentação a bibliotecas e APIs

note: (itstool) path: page/title (itstool) path: section/title
en: Documentation
pt_BR: Documentação

note: (itstool) path: item/p
en: Use gtk-doc with up-to-date settings for API documentation. (<link xref="#gtk-doc"/>)
pt_BR: Use gtk_doc com configurações atualizadas para documentação de API. (<link xref="#gtk-doc"/>)

note: (itstool) path: item/p
en: Use XML entities for including external symbols into the documentation. (<link xref="#build-system"/>)
pt_BR: Use entidades XML para inclusão de símbolos externos à documentação. (<link xref="#build-system"/>)

note: (itstool) path: item/p
en: Use a consistent, standard, table of contents for all API documentation to maintain familiarity. (<link xref="#standard-layout"/>)
pt_BR: Use uma tabela de conteúdos consistente e padrão para toda documentação de API para manter a familiaridade. (<link xref="#standard-layout"/>)

note: (itstool) path: item/p
en: Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to include in the gtk-doc build. (<link xref="#dbus-api"/>)
pt_BR: Use <cmd>gdbus-codegen</cmd> para gerar documentação de API do D-Bus para incluir na compilação de gtk-doc. (<link xref="#dbus-api"/>)

note: (itstool) path: item/p
en: Add introspection annotations to all API documentation. (<link xref="#introspection-annotations"/>)
pt_BR: Adicione anotações de introspecção a toda documentação de API. (<link xref="#introspection-annotations"/>)

note: (itstool) path: item/p
en: Add <code>Since</code> lines to all API documentation. (<link xref="#symbol-versioning"/>)
pt_BR: Adicione linhas <code>Since</code> para toda documentação de API. (<link xref="#symbol-versioning"/>)

note: (itstool) path: item/p
en: Enable gtk-doc tests. (<link xref="#keeping-up-to-date"/>)
pt_BR: Habilite testes de gtk-doc. (<link xref="#keeping-up-to-date"/>)

note: (itstool) path: section/p
en: The preferred documentation system for GNOME libraries is <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, which extracts inline comments from the code to let you build a <link href="http://docbook.org/">DocBook</link> document and collection of HTML pages. These can then be read in <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. A lot of GNOME’s infrastructure is built to handle with documentation written using gtk-doc.
pt_BR: O sistema de documentação preferido para bibliotecas do GNOME é o <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, o qual extrai comentários em linha do código e permite que você compile um documento <link href="http://docbook.org/">DocBook</link> e coleção de páginas HTML. Esses podem ser lidos em <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. Muito da infraestrutura do GNOME é construído para lidar com documentação escrita usando gtk-doc.

note: (itstool) path: section/title
en: Build System
pt_BR: Sistema de compilação

note: (itstool) path: section/p
en: To integrate gtk-doc into a project’s build system, follow the <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en"> instructions in the gtk-doc manual</link>. Note that while the <file>sections.txt</file> file is automatically generated the first time gtk-doc is run, it is not generated subsequently, and should be kept up to date manually. It should also be <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en"> in version control</link>.
pt_BR: Para integrar gtk-doc a um sistema de compilação do projeto, siga as <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en"> instruções no manual do gtk-doc</link>. Note que enquanto o arquivo <file>sections.txt</file> é gerado automaticamente na primeira vez que o gtk-doc é executado, ele não é gerado subsequentemente, e deve ser mantido atualizado. Ele também deve estar <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en"> no controle de versão</link>.

note: (itstool) path: section/p
en: gtk-doc’s <code>no-tmpl</code> flavour should be used, and XML mode should be used instead of SGML. (tmpl mode and SGML are both outdated and slower than XML.)
pt_BR: A opção <code>--flavour no-tmpl</code> do gtk-doc deve ser usada, e o modo XML deve ser usado no lugar do SGML. (modo tmpl e SGML estão ambos desatualizados e são mais lentos que XML.)

note: (itstool) path: section/p
en: If the package version is needed to be substituted into the documentation, create a file named <file>docs/version.xml.in</file>, containing:
pt_BR: Se a versão do pacote for necessária para ser substituída na documentação, crie um arquivo chamado <file>docs/version.xml.in</file>, contendo:

note: (itstool) path: section/p
en: Add it to <code>AC_CONFIG_FILES</code> in <file>configure.ac</file>, then include it into the main documentation file (<file>*-docs.xml</file>) using: <code>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code> in the <code>DOCTYPE</code> at the top of the document. The package version can then be used inline as <code>&amp;version;</code>.
pt_BR: Adicione-o a <code>AC_CONFIG_FILES</code> no <file>configure.ac</file>, então inclua-o ao arquivo central da documentação (<file>*-docs.xml</file>) usando: <code>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code> no <code>DOCTYPE</code> sobre o documento. A versão do pacote pode ser usada em linha como <code>&amp;version;</code>.

note: (itstool) path: section/title
en: Standard Layout
pt_BR: Layout padrão

note: (itstool) path: section/p
en: Using a standard layout for the table of contents, sections, appendices, etc. means the same <file><var>project-name</var>-docs.xml</file> template can be reused with few changes between projects. It also means the documentation layout is similar across all projects, making it more familiar to developers.
pt_BR: Usar um layout padrão para a tabela de conteúdos, seções, apêndices etc. significa que o mesmo modelo de <file><var>nome-do-projeto</var>-docs.xml</file> pode ser reusado com algumas alterações entre projetos. Ele também significa que o layout da documentação é similar por todos os projetos, fazendo dele mais familiar para os desenvolvedores.

note: (itstool) path: section/p
en: The following layout is suggested:
pt_BR: O layout a seguir é sugerido:

note: (itstool) path: listing/title
en: <file><var>project-name</var>-docs.xml</file>
pt_BR: <file><var>nome-do-projeto</var>-docs.xml</file>

note: (itstool) path: listing/desc
en: A template top-level gtk-doc file for a project
pt_BR: Um arquivo de modelo de nível superior do gtk-doc para um projeto

note: (itstool) path: section/title
en: Licensing
pt_BR: Licenciamento

note: (itstool) path: section/p
en: It is important to make the license used for API references clear, especially if they contain code examples which could be copied around.
pt_BR: É importante tornar a licença usada para referências de API bem clara, especialmente se elas contiverem exemplos de código que poderia ser copiado.

note: (itstool) path: section/p
en: Typically, projects use the same license for their API reference as for the project’s code itself, to avoid confusion. Some other projects use CC-BY-SA 3.0 for all their reference documentation. The choice is yours.
pt_BR: Geralmente, projetos usam a mesma licença para sua referência de API que para o código do projeto em si, para evitar confusão. Alguns projetos usam CC-BY-SA 3.0 para toda documentação de referência. A escolha é sua.

note: (itstool) path: section/p
en: As shown in the <link xref="#standard-layout">Standard Layout</link> you should include a <file>license.xml</file> in the top-level gtk-doc DocBook file which gives the full text of your documentation license.
pt_BR: Como mostrado no <link xref="#standard-layout">Layout padrão</link>, você deve incluir um <file>license.xml</file> no arquivo DocBook de nível superior do gtk-doc, o qual fornece o texto completo para sua licença de documentação.

note: (itstool) path: section/title
en: Public APIs
pt_BR: API pública

note: (itstool) path: section/p
en: All public APIs must have gtk-doc comments. For functions, these should be placed in the source file, directly above the function.
pt_BR: Todas APIs públicas devem ter comentários de gtk-doc. Para funções, essas devem ser colocadas no arquivo fonte, diretamente sobre a função.

note: (itstool) path: section/p
en: Documentation comments for macros, function types, class structs, etc. should be placed next to the definitions, typically in header files.
pt_BR: Comentários de documentação para macros, tipos de função, structs de classe, etc. devem ser colocados próximo às definições, geralmente em arquivos de cabeçalhos.

note: (itstool) path: section/p
en: Section introductions should be placed in the source file they describe, after the license header:
pt_BR: Introduções de seção devem ser colocadas no arquivo fonte que elas descrevem, após o cabeçalho de licença:

note: (itstool) path: section/p
en: Keep in mind that in order to include a function, macro, function type, or struct type, it needs to be listed in your documentation’s <file>modulename-sections.txt</file> file.
pt_BR: Tenha em mente que para incluir uma função, macro, tipo de função ou tipo de struct, ele precisa ser listado no arquivo de <file>nomemodulo-sections.txt</file> da documentação.

note: (itstool) path: section/p
en: To properly document a new class, it needs to be given its own section in <file>modulename-sections.txt</file>, needs to be included in your toplevel <file>modulename-docs.sgml</file>, and the <code>get_type()</code> function for your class needs to be listed in your <file>modulename.types</file>.
pt_BR: Para documentação adequadamente uma nova classe, ele precisa ser dado em sua própria seção no <file>nomemodulo-sections.txt</file> e a função <code>get_type()</code> para sua classe precisa ser listada em seu <file>nomemodulo.types</file>.

note: (itstool) path: section/title
en: Introspection Annotations
pt_BR: Anotações de introspecção

note: (itstool) path: section/p
en: Each gtk-doc comment should have appropriate <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations"> GObject introspection annotations</link>. These are useful for two reasons:
pt_BR: Cada comentário gtk-doc deve ter as <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">anotações de introspeção de GObject</link> adequada. Essa são úteis por dois motivos:

note: (itstool) path: item/p
en: They add important information about parameter types, nullability and memory management to the C API documentation generated by gtk-doc.
pt_BR: Elas adicionam informações importantes sobre tipos de parâmetros, anulabilidade e gerenciamento de memória para a documentação de API C gerada pelo gtk-doc.

note: (itstool) path: item/p
en: They allow public APIs to be automatically bound in other languages, such as Python or JavaScript.
pt_BR: Elas permitem que APIs públicas sejam automaticamente vinculadas a outras linguagens, tais como Python ou JavaScript.

note: (itstool) path: section/p
en: Introspection annotations add information to APIs (functions, function parameters, function return values, structures, GObject properties, GObject signals) which is otherwise not present in the machine readable C API and only exists in the form of human readable documentation or convention. They are very important.
pt_BR: Anotações de introspecção adicionam informações às APIs (funções, parâmetros de função, valor de retorno de função, estruturas, propriedades de GObject, sinais de GObject) nas quais, do contrário, não está presente na API C legível por máquina e existe apenas na forma de documentação legível por humano ou convenção. Elas são muito importantes.

note: (itstool) path: section/p
en: In gtk-doc comments, annotations should be preferred over human-readable equivalents. For example, when documenting a function parameter which may be <code>NULL</code>, use the <code>(nullable)</code> annotation rather than some text:
pt_BR: Em comentários de gtk-doc, anotações devem ser preferidos a equivalentes legíveis por humanos, Por exemplo, ao documentar o parâmetro de uma função que pode ser <code>NULL</code>, use a anotação <code>(nullable)</code> e, vez de algum texto:

note: (itstool) path: section/p
en: Instead of:
pt_BR: Em vez de:

note: (itstool) path: section/p
en: For more information on introspection, see the <link xref="introspection">introspection guidelines</link>.
pt_BR: Para mais informação sobre introspecção, veja as <link xref="introspection">diretrizes de introspecção</link>.

note: (itstool) path: section/title
en: Symbol Versioning
pt_BR: Versionamento de símbolo

note: (itstool) path: section/p
en: Whenever a symbol is added to the public API, it should have a documentation comment added. This comment should always contain a <code>Since</code> line with the package version number of the release which will first contain the new API. This should be the number currently in <file>configure.ac</file> if <link xref="versioning#release-process">post-release version incrementing</link> is being used.
pt_BR: Quando um símbolo é adicionado à API pública, ele deve ter um comentário de documentação adicionado. Esse comentário deve sempre conter uma linha <code>Since</code> com o número da versão de pacote do lançamento que primeiro conterá a nova API. Isso deve ser o número que está no <file>configure.in</file> se<link xref="versioning#release-process">incrementação de versão pós-lançamento</link> estiver sendo usado.

note: (itstool) path: section/p (itstool) path: example/p
en: For example:
pt_BR: Por exemplo:

note: (itstool) path: section/p
en: gtk-doc uses this information to generate indexes of the APIs added in each release. These should be added to the main <file>*-docs.xml</file> as an appendix:
pt_BR: gtk-doc usa essa informação para gerar índices das APIs adicionadas em cada lançamento. Essas devem ser adicionadas ao <file>*-docs.xml</file> principal como um apêndice:

note: (itstool) path: section/title
en: D-Bus APIs
pt_BR: APIs de D-Bus

note: (itstool) path: section/p
en: D-Bus interface descriptions contain documentation comments, and these can be extracted from the XML using <cmd>gdbus-codegen</cmd>, and turned into DocBook files to be included by gtk-doc.
pt_BR: Descrições de interface D-Bus contêm comentários de documentação, e podem ser extraídas do XML usando <cmd>gdbus-codegen</cmd> e transformadas em arquivos DocBook para serem incluídas pelo gtk-doc.

note: (itstool) path: section/p
en: The DocBook files can be included in the main <file>*-docs.xml</file> file using:
pt_BR: Os arquivos DocBook podem ser incluídos no arquivo <file>*-docs.xml</file> principal usando:

note: (itstool) path: section/p
en: The generated XML files must be included in the <code>content_files</code> variable in your gtk-doc <file>Makefile.am</file>, otherwise the build will fail. (This is to fix situations where the <code>builddir</code> does not equal the <code>srcdir</code>.)
pt_BR: Os arquivos XML gerados devem ser incluídos na variável <code>content_files</code> em seu <file>Makefile.am</file> de gtk-doc, do contrário a compilação vai falhar. (Isso é para corrigir situações nas quais <code>builddir</code> não é igual a <code>srcdir</code>.)

note: (itstool) path: section/title
en: Keeping Documentation Up to Date
pt_BR: Mantendo a documentação atualizada

note: (itstool) path: section/p
en: gtk-doc comes with support for checking the documentation with some basic tests. These check that all version indexes are included in the main <file>*-docs.xml</file> file and that all symbols are documented, amongst other things.
pt_BR: gtk-doc vem com suporte a verificação da documentação com alguns testes básicos. Essas verificações que toda versão indexa são incluídas ao arquivo <file>*-docs.xml</file> principal e que todos símbolos são documentados, além de outras coisas.

note: (itstool) path: section/p
en: These tests should always be enabled, by adding the following to your gtk-doc <file>Makefile.am</file>:
pt_BR: Esses testes devem sempre estar habilitados, adicionando o seguinte para seu <file>Makefile.am</file> de gtk-doc:

note: (itstool) path: section/p
en: They will then be run as part of <cmd>make check</cmd>.
pt_BR: Eles serão, então, executados como parte do <cmd>make check</cmd>.

note: (itstool) path: info/desc
en: Accessing the file system
pt_BR: Acessando o sistema de arquivos

note: (itstool) path: page/title
en: File System Access
pt_BR: Acesso ao sistema de arquivos

note: (itstool) path: synopsis/p
en: There are a few anti-patterns to consider when accessing the file system. This article assumes knowledge of the standard <link href="https://developer.gnome.org/gio/stable/GFile.html"><code>GFile</code></link>, <link href="https://developer.gnome.org/gio/stable/GInputStream.html"><code>GInputStream</code></link> and <link href="https://developer.gnome.org/gio/stable/GOutputStream.html"><code>GOutputStream</code></link> APIs.
pt_BR: Há alguns antipadrões a serem considerados ao acessar o sistema de arquivos. Esse artigo presume conhecimento das APIs <link href="https://developer.gnome.org/gio/stable/GFile.html"><code>GFile</code></link>, <link href="https://developer.gnome.org/gio/stable/GInputStream.html"><code>GInputStream</code></link> e <link href="https://developer.gnome.org/gio/stable/GOutputStream.html"><code>GOutputStream</code></link> padrões.

note: (itstool) path: item/p
en: Use asynchronous I/O for file access. (<link xref="#asynchronous-io"/>)
pt_BR: Use E/S assíncrona para acesso de arquivo. (<link xref="#asynchronous-io"/>)

note: (itstool) path: item/p
en: Always use appropriate functions to construct file names and paths. (<link xref="#file-path-construction"/>)
pt_BR: Sempre use funções adequadas para construir nomes e caminhos de arquivos . (<link xref="#file-path-construction"/>)

note: (itstool) path: item/p
en: Validate file paths are in the expected directories before using them. (<link xref="#path-validation-and-sandboxing"/>)
pt_BR: Valide caminhos de arquivos que estão em diretórios esperados antes de usá-los. (<link xref="#path-validation-and-sandboxing"/>)

note: (itstool) path: item/p
en: Use mandatory access control profiles to enforce constraints on file access. (<link xref="#path-validation-and-sandboxing"/>)
pt_BR: Use perfis obrigatórios de controle de acesso para reforçar restrições de acesso de arquivos. (<link xref="#path-validation-and-sandboxing"/>)

note: (itstool) path: section/title
en: Asynchronous I/O
pt_BR: E/S assíncrona

note: (itstool) path: section/p
en: Almost all I/O should be performed asynchronously. That is, without blocking the <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html">GLib main context</link>. This can be achieved by always using the <code>*_async()</code> and <code>*_finish()</code> variants of each I/O function.
pt_BR: Quase toda E/S deve ser feita assincronamente, ou seja, sem bloqueio do <link href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html">contexto principal do GLib</link>. Isso pode ser alcançado por sempre usar as variantes <code>*_async()</code> e <code>*_finish()</code> de cada função de E/S.

note: (itstool) path: example/p
en: For example, <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read-async"><code>g_input_stream_read_async()</code></link> rather than <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read"><code>g_input_stream_read()</code></link>.
pt_BR: Por exemplo, <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read-async"><code>g_input_stream_read_async()</code></link> em vez de <link href="https://developer.gnome.org/gio/stable/GInputStream.html#g-input-stream-read"><code>g_input_stream_read()</code></link>.

note: (itstool) path: section/p
en: Synchronous I/O blocks the main loop, which means that other events, such as user input, incoming networking packets, timeouts and idle callbacks, are not handled until the blocking function returns.
pt_BR: E/S síncrona bloqueia o loop principal, o que significa que outros eventos, tal como entrada de usuário, chegada de pacotes de rede, expiração de tempo limite e retorno de chamada ocioso, não são tratados até que a função bloqueadora retorne.

note: (itstool) path: section/p
en: Synchronous I/O is acceptable in certain circumstances where the overheads of scheduling an asynchronous operation exceed the costs of local synchronous I/O on Linux. For example, making a small read from a local file, or from a virtual file system such as <file>/proc</file>. For such reads, the low level functions <code>g_open()</code>, <code>read()</code> and <code>g_close()</code> should be used rather than GIO.
pt_BR: E/S síncrona é aceitável em certas circunstâncias nas quais a sobrecarga de agendar uma operação assíncrona excede o custo de E/S síncrona local no Linux. Por exemplo, fazer uma leitura pequena de um arquivo local, ou de um sistema de arquivos virtual tal como <file>/proc</file>. Para tais leituras, as funções de baixo nível <code>g_open()</code>, <code>read()</code> e <code>g_close()</code> devem ser usadas, em vez do GIO.

note: (itstool) path: section/p
en: Files in the user’s home directory do <em>not</em> count as local, as they could be on a networked file system.
pt_BR: Arquivos no diretório pessoal do usuário <em>não</em> contam como locais, pois eles podem estar em um sistema de arquivos de rede.

note: (itstool) path: section/p
en: Note that the alternative – running synchronous I/O in a separate thread – is highly discouraged; see the <link xref="threading#when-to-use-threading">threading guidelines</link> for more information.
pt_BR: Note que a alternativa – executar E/S síncrona em uma thread separada – é altamente desencorajada; veja as <link xref="threading#when-to-use-threading">diretrizes de thread</link> para mais informações.

note: (itstool) path: section/title
en: File Path Construction
pt_BR: Construção de caminho de arquivo

note: (itstool) path: section/p
en: File names and paths are not normal strings: on some systems, they can use a character encoding other than UTF-8, while normal strings in GLib are guaranteed to always use UTF-8. For this reason, special functions should be used to build and handle file names and paths. (Modern Linux systems almost universally use UTF-8 for filename encoding, so this is not an issue in practice, but the file path functions should still be used for compatibility with systems such as Windows, which use UTF-16 filenames.)
pt_BR: Nomes e caminhos de arquivos não são strings normais: em alguns sistemas, eles podem usar uma codificação de caracteres diferente de UTF-8, enquanto strings normais no GLib têm a garantia de sempre usar UTF-8. Por este motivo, funções especiais devem ser usadas para compilar e tratar nomes e caminhos de arquivos. (Sistemas Linux modernos quase que universalmente usam UTF-8 para codificação de nome de arquivo, então isso não é um problema na prática, mas as funções de caminho de arquivo ainda devem ser usadas para compatibilidade com sistemas como o Windows, que usam nomes de arquivos UTF-16.)

note: (itstool) path: example/p
en: For example, file paths should be built using <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-build-filename"><code>g_build_filename()</code></link> rather than <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strconcat"><code>g_strconcat()</code></link>.
pt_BR: Por exemplo, caminhos de arquivos devem ser construídos usando <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-build-filename"><code>g_build_filename()</code></link> em vez de <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strconcat"><code>g_strconcat()</code></link>.

note: (itstool) path: section/p
en: Doing so makes it clearer what the code is meant to do, and also eliminates duplicate directory separators, so the returned path is canonical (though not necessarily absolute).
pt_BR: Fazer isso deixa mais claro qual é a intenção do código e também elimina separadores duplicados de diretórios, de forma que o caminho retornado é canonical (apesar de não necessariamente absoluto).

note: (itstool) path: example/p
en: As another example, paths should be disassembled using <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-basename"><code>g_path_get_basename()</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname"><code>g_path_get_dirname()</code></link> rather than <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strrstr"><code>g_strrstr()</code></link> and other manual searching functions.
pt_BR: Como um outro exemplo, caminhos devem ser desmembrados usando <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-basename"><code>g_path_get_basename()</code></link> e <link href="https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-path-get-dirname"><code>g_path_get_dirname()</code></link> em vez de <link href="https://developer.gnome.org/glib/stable/glib-String-Utility-Functions.html#g-strrstr"><code>g_strrstr()</code></link> e outras funções manuais de pesquisa.

note: (itstool) path: section/title
en: Path Validation and Sandboxing
pt_BR: Validação de caminho e <em>sandboxing</em>

note: (itstool) path: section/p
en: If a filename or path comes from external input, such as a web page or user input, it should be validated to ensure that putting it into a file path will not produce an arbitrary path. For example if a filename is constructed from the constant string <file>~/</file> plus some user input, if the user inputs <file>../../etc/passwd</file>, they can (potentially) gain access to sensitive account information, depending on which user the program is running as, and what it does with data loaded from the constructed path.
pt_BR: Se um nome ou caminho de arquivo vem com uma entrada externa, tal como uma página web ou entrada de usuário, ele deve ser validado para garantir que colocá-lo em um caminho de arquivo não produzirá um caminho arbitrário. Por exemplo, se um nome de arquivo é construído a partir de uma string constante <file>~/</file> junto com alguma entrada de usuário, se o usuário insere <file>./../etc/passwd</file>, eles podem (potencialmente) ganhar acesso a informação sensível de contas, dependendo de com qual usuário o programa está sendo executado e o que ele faz com os dados carregados a partir do caminho construído.

note: (itstool) path: section/p
en: This can be avoided by validating constructed paths before using them, using <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-resolve-relative-path"><code>g_file_resolve_relative_path()</code></link> to convert any relative paths to absolute ones, and then validating that the path is beneath a given root sandboxing directory appropriate for the operation. For example, if code downloads a file, it could validate that all paths are beneath <file>~/Downloads</file>, using <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-has-parent"><code>g_file_has_parent()</code></link>.
pt_BR: Isso pode ser evitado por meio de uma validação dos caminhos construídos antes de usá-los usando <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-resolve-relative-path"><code>g_file_resolve_relative_path()</code></link> para converter quaisquer caminhos relativos para absolutos e, então, validar se aqueles caminhos estão dentro de um diretório raiz de <em>sandbox</em> apropriado para a operação. Por exemplo, se um código baixa um arquivo, ele poderia validar se aqueles caminhos estejam dentro de <file>~/Downloads</file>, usando <link href="https://developer.gnome.org/gio/stable/GFile.html#g-file-has-parent"><code>g_file_has_parent()</code></link>.

note: (itstool) path: section/p
en: As a second line of defence, all projects which access the file system should consider providing a mandatory access control profile, using a system such as <link href="http://apparmor.net/">AppArmor</link> or <link href="http://selinuxproject.org/">SELinux</link>, which limits the directories and files they can read from and write to.
pt_BR: Como uma segunda linha de defesa, todos os projetos que acessam o sistema de arquivos devem considerar fornecer um perfil obrigatório de controle de acesso, usando um sistema tal como <link href="http://apparmor.net/">AppArmor</link> ou <link href="http://selinuxproject.org/">SELinux</link> que limita os diretórios e arquivos nos quais eles podem ler de ou escrever em.

note: (itstool) path: info/desc
en: Runtime error handling and reporting
pt_BR: Tratamento e relatório de erro em tempo de execução

note: (itstool) path: section/title
en: GError Usage
pt_BR: Uso do GError

note: (itstool) path: section/p
en: <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html"><code>GError</code></link> is the standard error reporting mechanism for GLib-using code, and can be thought of as a C implementation of an <link href="http://en.wikipedia.org/wiki/Exception_handling">exception</link>.
pt_BR: <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html"><code>GError</code></link> é o mecanismo padrão de relatório de erro para códigos usando GLib e pode ser pensado como uma implementação C de uma <link href="http://en.wikipedia.org/wiki/Exception_handling">exceção</link>.

note: (itstool) path: section/p
en: Any kind of runtime failure (anything which is not a <link xref="preconditions">programmer error</link>) must be handled by including a <code>GError**</code> parameter in the function, and setting a useful and relevant GError describing the failure, before returning from the function. Programmer errors must not be handled using GError: use assertions, pre-conditions or post-conditions instead.
pt_BR: Qualquer tipo de falha em tempo de execução (qualquer coisa que não seja um <link xref="preconditions">erro de programação</link>) deve ser tratado com a inclusão de um parâmetro <code>GError**</code> na função e definição de um GError útil e relevante que descreva a falha, antes de retornar a função. Os erros de programação não devem ser tratados usando GError: use asserções, pré-condições ou pós-condições.

note: (itstool) path: section/p
en: GError should be used in preference to a simple return code, as it can convey more information, and is also supported by all GLib tools. For example, <link xref="introspection">introspecting an API</link> will automatically detect all GError parameters so that they can be converted to exceptions in other languages.
pt_BR: O GError deve ser usado como preferência a um código de retorno simples, pois ele pode transmitir mais informações e também tem suporte em todas as ferramentas em GLib. Por exemplo, <link xref="introspection">introspecção de uma API</link> detectará automaticamente todos os parâmetros de GError de forma que eles possam ser convertidos para exceções em outros idiomas.

note: (itstool) path: section/p
en: Printing warnings to the console must not be done in library code: use a GError, and the calling code can propagate it further upwards, decide to handle it, or decide to print it to the console. Ideally, the only code which prints to the console will be top-level application code, and not library code.
pt_BR: A impressão de avisos para o console não deve ser feita no código da biblioteca: use um GError e o código de chamada pode propagá-lo mais para cima, decidir tratá-lo ou decidir imprimi-lo para o console. Idealmente, o único código que imprime para o console será um código de aplicativo topo de nível, e não um código de biblioteca.

note: (itstool) path: section/p
en: Any function call which can take a <code>GError**</code>, <em>should</em> take such a parameter, and the returned GError should be handled appropriately. There are very few situations where ignoring a potential error by passing <code>NULL</code> to a <code>GError**</code> parameter is acceptable.
pt_BR: Qualquer chamada de função que possa levar um <code>GError**</code>, <em>deve</em> levar tal parâmetro e o GError retornado deve ser tratado apropriadamente. Há muito poucas situações nas quais ignorar um erro em potencial passando <code>NULL</code> para um parâmetro <code>GError**</code> é aceitável.

note: (itstool) path: section/p
en: The GLib API documentation contains a <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#glib-Error-Reporting.description">full tutorial for using GError</link>.
pt_BR: A documentação de API do GLib contém um <link href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#glib-Error-Reporting.description">tutorial completo sobre o uso de GError</link>.

note: (itstool) path: info/desc
en: Linked lists and container types
pt_BR: Listas vinculadas e tipos contêineres

note: (itstool) path: section/title
en: GList Usage
pt_BR: Uso do GList

note: (itstool) path: section/p
en: GLib provides several container types for sets of data: <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html"><code>GList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Singly-Linked-Lists.html"><code>GSList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html"><code>GPtrArray</code></link> and <link href="https://developer.gnome.org/glib/stable/glib-Arrays.html"><code>GArray</code></link>.
pt_BR: GLib fornece vários tipos contêineres para conjuntos de dados: <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html"><code>GList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Singly-Linked-Lists.html"><code>GSList</code></link>, <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html"><code>GPtrArray</code></link> e <link href="https://developer.gnome.org/glib/stable/glib-Arrays.html"><code>GArray</code></link>.

note: (itstool) path: section/p
en: It has been common practice in the past to use GList in all situations where a sequence or set of data needs to be stored. This is inadvisable — in most situations, a GPtrArray should be used instead. It has lower memory overhead (a third to a half of an equivalent list), better cache locality, and the same or lower algorithmic complexity for all common operations. The only typical situation where a GList may be more appropriate is when dealing with ordered data, which requires expensive insertions at arbitrary indexes in the array.
pt_BR: Foi uma prática comum no passado usar GList e, todas situações nas quais uma sequência ou conjunto de dados precisa ser armazenada(o). Isso não é recomendável — na maioria das situações, um GPtrArray deve ser usado. Ele faz menor uso de memória (um terço a metade de uma lista equivalente), melhora localidade de cache e a mesma ou menor complexidade algorítmica para todas as operações comuns. A única situação típica na qual um GList pode ser mais apropriado é ao lidar com dados ordenados, que requer inserções custosas em índices arbitrários no vetor.

note: (itstool) path: section/p
en: If linked lists are used, be careful to keep the complexity of operations on them low, using standard CS complexity analysis. Any operation which uses <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth"><code>g_list_nth()</code></link> or <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth-data"><code>g_list_nth_data()</code></link> is almost certainly wrong. For example, iteration over a GList should be implemented using the linking pointers, rather than a incrementing index:
pt_BR: Se listas vinculadas forem usadas, tenha o cuidado de manter baixa a complexidade das operações nelas, usando análise padrão de complexidade CS. Qualquer operação que usa <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth"><code>g_list_nth()</code></link> ou <link href="https://developer.gnome.org/glib/2.30/glib-Doubly-Linked-Lists.html#g-list-nth-data"><code>g_list_nth_data()</code></link> está quase certamente errada. Por exemplo, interação por um GList deve ser implementada usando os ponteiros vinculantes, em vez de um índice incremental:

note: (itstool) path: section/code
en: GList *some_list, *l;
    
    for (l = some_list; l != NULL; l = l-&gt;next)
      {
        gpointer element_data = l-&gt;data;
    
        /* Do something with @element_data. */
      }
pt_BR: GList *some_list, *l;
    
    for (l = some_list; l != NULL; l = l-&gt;next)
      {
        gpointer element_data = l-&gt;data;
    
        /* Faz alguma coisa com @element_data. */
      }

note: (itstool) path: section/p
en: Using an incrementing index instead results in a quadratic decrease in performance (<em>O(N^2)</em> rather than <em>O(N)</em>):
pt_BR: Usar um índice incremental pode resultar em um decréscimo quadrático no desempenho (<em>O(N^2)</em> em vez de <em>O(N)</em>):

note: (itstool) path: section/code
en: GList *some_list;
    guint i;
    
    /* This code is inefficient and should not be used in production. */
    for (i = 0; i &lt; g_list_length (some_list); i++)
      {
        gpointer element_data = g_list_nth_data (some_list, i);
    
        /* Do something with @element_data. */
      }
pt_BR: GList *some_list;
    guint i;
    
    /* Esse código é ineficiente e não deve ser usado em produção. */
    for (i = 0; i &lt; g_list_length (some_list); i++)
      {
        gpointer element_data = g_list_nth_data (some_list, i);
    
        /* Faz alguma coisa com @element_data. */
      }

note: (itstool) path: section/p
en: The performance penalty comes from <code>g_list_length()</code> and <code>g_list_nth_data()</code> which both traverse the list (<em>O(N)</em>) to perform their operations.
pt_BR: A penalidade no desempenho vem de <code>g_list_length()</code> e de <code>g_list_nth_data()</code>, os quais percorrem a lista (<em>O(N)</em>) para realizar suas operações.

note: (itstool) path: section/p
en: Implementing the above with a GPtrArray has the same complexity as the first (correct) GList implementation, but better cache locality and lower memory consumption, so will perform better for large numbers of elements:
pt_BR: Implementar o código acima com um GPtrArray tem a mesma complexidade que a primeira (correta) implementação de GList, mas com melhor localidade de cache e menor consumo de memória, de forma a executar melhor para grandes números de elementos:

note: (itstool) path: section/code
en: GPtrArray *some_array;
    guint i;
    
    for (i = 0; i &lt; some_array-&gt;len; i++)
      {
        gpointer element_data = some_array-&gt;pdata[i];
    
        /* Do something with @element_data. */
      }
pt_BR: GPtrArray *some_array;
    guint i;
    
    for (i = 0; i &lt; some_array-&gt;len; i++)
      {
        gpointer element_data = some_array-&gt;pdata[i];
    
        /* Faz alguma coisa com @element_data. */
      }

note: (itstool) path: credit/name
en: GNOME Foundation
pt_BR: A Fundação GNOME

note: (itstool) path: info/desc (itstool) path: page/title
en: GNOME Programming Guidelines
pt_BR: Diretrizes de programação do GNOME

[ctx: link:trail]
note: (itstool) path: info/title
en: Programming Guidelines
pt_BR: Diretrizes de programação

note: (itstool) path: page/p
en: This article contains several guidelines and suggestions for programmers working in and with the GNOME stack. This is intended for programmers to know about the development processes, conventions and philosophies behind GNOME applications and the stack of libraries supporting them. By knowing “the way things are done” in the GNOME ecosystem, it is hoped that programmers will find use of GNOME APIs and development of new applications easier and more natural, and will produce code which is legible and maintainable over a long period of time by a diverse team of programmers.
pt_BR: Esse artigo contém várias diretrizes e sugestões para programadores que estejam trabalhando em e com recursos do GNOME. Ele é direcionado para programadores saberem sobre os processos de desenvolvimento, convenções e filosofias por trás dos aplicativos do GNOME e a pilha de bibliotecas por trás destes. Sabendo “a forma como as coisas são feitas” no ecossistema do GNOME, espera-se que programadores encontrem uso nas APIs do GNOME e um desenvolvimento de novos aplicativos mais fácil e mais natural, e produzirão código que seja legível e sustentável por um longo período de tempo por uma equipe diversa de programadores.

note: (itstool) path: page/p
en: This guide has a two-fold purpose:
pt_BR: Esse guia tem um propósito duplo:

note: (itstool) path: item/p
en: To give you good suggestions on how to write code for GNOME or using GNOME technologies. This will help you write code that is consistent with best practices, and that will be accepted by the community. This will also lead to code that is a pleasure to work on.
pt_BR: Fornecer boas sugestões sobre como escrever código para GNOME e usar tecnologias do GNOME. Isso lhe ajudará a escrever código que é consistente com as melhores práticas, e que serão aceitas pela comunidade. Isso também levará a um código no qual seja agradável de trabalhar.

note: (itstool) path: item/p
en: To transmit the knowledge we have gotten over the years on how to keep the GNOME project sustainable, even when people’s contributions increase or decrease.
pt_BR: Transmitir o conhecimento que nós obtivemos pelos anos sobre como manter o projeto GNOME sustentável, mesmo quando as contribuições das pessoas aumentaram ou diminuírem.

[ctx: link:trail]
note: (itstool) path: info/title
en: General Guidelines
pt_BR: Diretrizes gerais

note: (itstool) path: section/title
en: General Guidelines
pt_BR: Diretrizes gerais

[ctx: link:trail]
note: (itstool) path: info/title
en: Maintainer Guidelines
pt_BR: Diretrizes de manutenção

note: (itstool) path: section/title
en: Maintainer Guidelines
pt_BR: Diretrizes de manutenção

[ctx: link:trail]
note: (itstool) path: info/title
en: Specific How-Tos
pt_BR: “Como fazer” específicos

note: (itstool) path: section/title
en: Specific How-Tos
pt_BR: “Como fazer” específicos

[ctx: link:trail]
note: (itstool) path: info/title
en: References
pt_BR: Referências

note: (itstool) path: section/title
en: References
pt_BR: Referências

note: (itstool) path: info/desc
en: GObject Introspection support in library code
pt_BR: Suporte a GObject Introspection em código de biblioteca

note: (itstool) path: synopsis/p
en: <link href="https://wiki.gnome.org/Projects/GObjectIntrospection"> GObject introspection</link> (abbreviated ‘GIR’) is a system which extracts APIs from C code and produces binary type libraries which can be used by non-C language bindings, and other tools, to <link href="http://en.wikipedia.org/wiki/Type_introspection">introspect</link> or <link href="http://en.wikipedia.org/wiki/Language_binding">wrap</link> the original C libraries. It uses a system of annotations in documentation comments in the C code to expose extra information about the APIs which is not machine readable from the code itself.
pt_BR: <link href="https://wiki.gnome.org/Projects/GObjectIntrospection"> GObject introspection</link> (abreviado para ‘GIR’) é um sistema que extrai APIs de código C e produz bibliotecas de tipo binário que podem ser usadas por ligações de linguagem não C, e outras ferramentas, para <link href="http://en.wikipedia.org/wiki/Type_introspection">examinar</link> ou <link href="http://en.wikipedia.org/wiki/Language_binding">interfacear</link> as bibliotecas C originais. Ele usa um sistema de anotações em comentários de documentação no código C para expor informações extras sobre as APIs que não sejam legíveis por máquina a partir do próprio código.

note: (itstool) path: section/title
en: Using Introspection
pt_BR: Usando a introspecção

note: (itstool) path: section/title
en: API Design
pt_BR: Design de API

note: (itstool) path: info/desc
en: Logging debug and information output from libraries and programs
pt_BR: Registrando saída de depuração e de informação de bibliotecas e programas

note: (itstool) path: section/title
en: GLib Logging Framework
pt_BR: Framework de registro de Glib

note: (itstool) path: section/title
en: Exceptions
pt_BR: Exceções

note: (itstool) path: section/title
en: journald Integration
pt_BR: Integração com journald

note: (itstool) path: section/title
en: Log Rotation
pt_BR: Rotação de registro

note: (itstool) path: info/desc
en: GLib main contexts, invoking functions in other threads, and the event loop
pt_BR: Contextos centrais de GLib, invocando funções em outras threads e loop de eventos

note: (itstool) path: page/title
en: GLib Main Contexts
pt_BR: Contextos centrais de GLib

note: (itstool) path: section/title
en: What is <code>GMainContext</code>?
pt_BR: O que é <code>GMainContext</code>?

note: (itstool) path: section/title
en: What is <code>GMainLoop</code>?
pt_BR: O que é <code>GMainLoop</code>?

note: (itstool) path: section/title
en: Default Contexts
pt_BR: Contextos padrões

note: (itstool) path: section/title
en: Using <code>GMainContext</code> in a Library
pt_BR: Usando <code>GMainContext</code> em uma biblioteca

note: (itstool) path: section/title
en: Principles of Invocation
pt_BR: Princípios da invocação

note: (itstool) path: info/desc
en: Managing memory allocation and deallocation in C
pt_BR: Gerindo alocação e desalocação de memória no C

note: (itstool) path: page/title
en: Memory Management
pt_BR: Gerenciamento de memória

note: (itstool) path: section/title
en: Principles of Memory Management
pt_BR: Princípios do gerenciamento de memória

note: (itstool) path: section/p
en: For example, consider the functions:
pt_BR: Por exemplo, considere as funções:

note: (itstool) path: td/p
en: Unused
pt_BR: Não utilizado

note: (itstool) path: section/title
en: Reference Counting
pt_BR: Contagem de referência

note: (itstool) path: info/desc
en: Avoiding symbol conflicts between libraries by namespacing all APIs
pt_BR: Evite conflitos de símbolos entre bibliotecas atribuindo espaço de nomes a todas APIs

note: (itstool) path: page/title
en: Namespacing
pt_BR: Espaço de nomes

note: (itstool) path: info/desc
en: Writing libraries to be future proof through parallel installation
pt_BR: Escrevendo bibliotecas para serem a prova de futuro por meio de instalação paralela

note: (itstool) path: page/title
en: Parallel Installability
pt_BR: Instabilidade paralela

note: (itstool) path: section/title
en: Justification
pt_BR: Justificação

note: (itstool) path: section/title
en: Libraries
pt_BR: Bibliotecas

note: (itstool) path: info/desc
en: Contract programming with checks on function input and output
pt_BR: Contrate programação com verificações em função de entrada e saída

note: (itstool) path: page/title (itstool) path: section/title
en: Pre- and Post-Conditions
pt_BR: Pré e pós-condições

note: (itstool) path: item/title
en: Assertions
pt_BR: Asserções

note: (itstool) path: item/title
en: Validation
pt_BR: Validação

note: (itstool) path: info/desc
en: Moving computation out of the main thread into worker threads
pt_BR: Movendo computação da thread principal para threads de trabalho

note: (itstool) path: section/title
en: Debugging
pt_BR: Depuração

note: (itstool) path: info/desc
en: Using the right tool for various tasks
pt_BR: Usando a ferramenta certa para várias tarefas

note: (itstool) path: page/title
en: Tooling
pt_BR: Ferramentas

note: (itstool) path: page/p
en: Development tools are much more than just a text editor and a compiler. Correct use of the right tools can drastically ease debugging and tracking down of complex problems with memory allocation and system calls, amongst other things. Some of the most commonly used tools are described below; other tools exist for more specialized use cases, and should be used when appropriate.
pt_BR: Ferramentas de desenvolvimento são muito mais do que um editor de texto e um compilador. O uso correto das ferramentas certas pode facilitar drasticamente a depuração e o rastreamento de problemas complexos com alocação de memória e chamadas de sistema; além de outras coisas. Algumas das ferramentas mais comumente usadas são descritas abaixo; outras ferramentas existem para casos de uso mais especializados e devem ser usados quando apropriado.

note: (itstool) path: page/p
en: An overarching principle to use when developing is to always have as many debugging options enabled as possible, rather than keeping them disabled until near release time. By constantly testing code with all available debug tooling, bugs can be caught early on, before they become ingrained in code and thus harder to remove.
pt_BR: Um princípio geral a se usar quando se está desenvolvendo é sempre ter tantas opções de depuração habilitadas quanto possível, em vez de mantê-las desabilitadas até próximo da data de lançamento. Ao testar o código constantemente com todas as ferramentas de depuração disponível, erros podem ser encontrados desde cedo, antes que eles façam parte do código e, portanto, mais seja difícil de removê-los.

note: (itstool) path: page/p
en: Practically, this means having all compiler and other tool warnings enabled and set to fail the build process with an error if they are emitted.
pt_BR: Na prática, isso significa ter todos os avisos, do compilador e de outras ferramentas, habilitados e definidos para falhar no processo de compilação com um erro se forem emitidos.

note: (itstool) path: item/p
en: Compile frequently with a second compiler. (<link xref="#gcc-and-clang"/>)
pt_BR: Compile com frequência com um segundo compilador. (<link xref="#gcc-and-clang"/>)

note: (itstool) path: item/p
en: Enable a large selection of compiler warnings and make them fatal. (<link xref="#gcc-and-clang"/>)
pt_BR: Habilite uma seleção grande de avisos de compilador e faça-os falhar. (<link xref="#gcc-and-clang"/>)

note: (itstool) path: item/p
en: Use GDB to debug and step through code. (<link xref="#gdb"/>)
pt_BR: Use GDB para depurar e passear pelo código. (<link xref="#gdb"/>)

note: (itstool) path: item/p
en: Use Valgrind to analyze memory usage, memory errors, cache and CPU performance and threading errors. (<link xref="#valgrind"/>)
pt_BR: Use Valgrind para analisar o uso de memória, erros de memória, cache e desempenho da CPU e erros em threads. (<link xref="#valgrind"/>)

note: (itstool) path: item/p
en: Use gcov and lcov to analyze unit test coverage. (<link xref="#gcov-and-lcov"/>)
pt_BR: Use gcov e lcov para analisar a cobertura de teste de unidade. (<link xref="#gcov-and-lcov"/>)

note: (itstool) path: item/p
en: Use compiler sanitizers to analyze memory, thread and undefined behavior problems. (<link xref="#sanitizers"/>)
pt_BR: Use sanitizadores de compilador para analisar problemas de memória, thread e comportamentos indefinidos. (<link xref="#sanitizers"/>)

note: (itstool) path: item/p
en: Submit to Coverity as a cronjob and eliminate static analysis errors as they appear. (<link xref="#coverity"/>)
pt_BR: Envie para Coverity como um cronjob e elimine erros de análise estática na medida em que eles aparecem. (<link xref="#coverity"/>)

note: (itstool) path: item/p
en: Use Clang static analyzer and Tartan regularly to eliminate statically analysable errors locally. (<link xref="#clang-static-analyzer"/>)
pt_BR: Use o analisador estático do Clang e o Tartan regularmente para eliminar localmente erros analisáveis estaticamente

note: (itstool) path: section/title
en: GCC and Clang
pt_BR: GCC e Clang

note: (itstool) path: section/p
en: <link href="https://gcc.gnu.org/onlinedocs/gcc/">GCC</link> is the standard C compiler for Linux. An alternative exists in the form of <link href="http://clang.llvm.org/docs/UsersManual.html">Clang</link>, with comparable functionality. Choose one (probably GCC) to use as a main compiler, but occasionally use the other to compile the code, as the two detect slightly different sets of errors and warnings in code. Clang also comes with a static analyzer tool which can be used to detect errors in code without compiling or running it; see <link xref="#clang-static-analyzer"/>.
pt_BR: <link href="https://gcc.gnu.org/onlinedocs/gcc/">GCC</link> é o compilador C padrão para Linux. Existe uma alternativa na forma de <link href="http://clang.llvm.org/docs/UsersManual.html">Clang</link>, com funcionalidade comparável. Escolha um (provavelmente GCC) para usar como compilador principal, mas ocasionalmente use o outro para compilar o código, já que os dois detectam um conjunto um pouco diferente de erros e avisos no código. Clang também vem com uma ferramenta de análise estática que pode ser usada para detectar erros no código sem precisar compilá-lo e executá-lo; veja <link xref="#clang-static-analyzer"/>.

note: (itstool) path: section/p
en: Both compilers should be used with as many warning flags enabled as possible. Although compiler warnings do occasionally provide false positives, most warnings legitimately point to problems in the code, and hence should be fixed rather than ignored. A development policy of enabling all warning flags and also specifying the <code>-Werror</code> flag (which makes all warnings fatal to compilation) promotes fixing warnings as soon as they are introduced. This helps code quality. The alternative of ignoring warnings leads to long debugging sessions to track down bugs caused by issues which would have been flagged up by the warnings. Similarly, ignoring warnings until the end of the development cycle, then spending a block of time enabling and fixing them all wastes time.
pt_BR: Ambos compiladores devem ser usados com tantos sinalizadores de avisos habilitados quanto possível. Apesar de avisos de compilador de vez em quando fornecerem falsos positivos, a maioria dos avisos legitimamente aponta para problemas no código e, portanto, devem ser corrigidos em vez de ignorados. Uma política de desenvolvimento de habilitar todos sinalizadores de avisos e também especificar o sinalizador <code>-Werror</code> (que torna todos os avisos em fatais para compilação) promove correção de avisos assim que forem introduzidos. Isso ajuda na qualidade do código. A alternativa de ignorar avisos leva a longas sessões de depuração para rastrear erros causados por problemas que teriam sido levantados pelos avisos. Similarmente, ignorar avisos até o fim do ciclo de desenvolvimento para, em um momento posterior, gastar um pedaço de tempo habilitando e corrigindo todos eles é uma perda de tempo.

note: (itstool) path: section/p
en: Both GCC and Clang support a wide range of compiler flags, only some of which are related to modern, multi-purpose code (for example, others are outdated or architecture-specific). Finding a reasonable set of flags to enable can be tricky, and hence the <link href="http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html"> <code>AX_COMPILER_FLAGS</code></link> macro exists.
pt_BR: Ambos GCC e Clang oferecem suporte a um amplo alcance de sinalizadores de compilador, estando apenas alguns relacionados a um código moderno e multipropósito (por exemplo, outros estão desatualizados e são para alguma arquitetura específica). Encontrar um conjunto razoável de sinalizadores para habilitar pode ser complicado e por isto que a macro <link href="http://www.gnu.org/software/autoconf-archive/ax_compiler_flags.html"> <code>AX_COMPILER_FLAGS</code></link> existe.

note: (itstool) path: section/p
en: <code>AX_COMPILER_FLAGS</code> enables a consistent set of compiler warnings, and also tests that the compiler supports each flag before enabling it. This accounts for differences in the set of flags supported by GCC and Clang. To use it, add <code>AX_COMPILER_FLAGS</code> to <file>configure.ac</file>. If you are using in-tree copies of autoconf-archive macros, copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_compiler_flags.m4"> <file>ax_compiler_flags.m4</file></link> to the <file>m4/</file> directory of your project. Note that it depends on the following autoconf-archive macros which are GPL-licenced so potentially cannot be copied in-tree. They may have to remain in autoconf-archive, with that as a build time dependency of the project:
pt_BR: <code>AX_COMPILER_FLAGS</code> permite um conjunto consistente de avisos de compilador e também testa se o computador oferece suporte a cada sinalizador antes de habilitá-lo. Isso conta para diferenças no conjunto de sinalizadores aos quais GCC e Clang oferecem suporte. Para usá-lo, adicione <code>AX_COMPILER_FLAGS</code> ao <file>configure.ac</file>. Se você está usando cópias de macros autoconf-archive na árvore do projeto, copie <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_compiler_flags.m4"> <file>ax_compiler_flags.m4</file></link> para o diretório <file>m4/</file> deste. Note que ele depende das macros de autoconf-archive a seguir, as quais são licenciadas sob GPL e, portanto, potencialmente não podem ser copiadas para a árvore. Elas podem permanecer no autoconf-archive, com este como uma dependência de tempo de compilação do projeto:

note: (itstool) path: section/p
en: <code>AX_COMPILER_FLAGS</code> supports disabling <code>-Werror</code> for release builds, so that releases may always be built against newer compilers which have introduced more warnings. Set its third parameter to ‘yes’ for release builds (and only release builds) to enable this functionality. Development and CI builds should always have <code>-Werror</code> enabled.
pt_BR: <code>AX_COMPILER_FLAGS</code> oferece suporte a desabilitar <code>-Werror</code> para compilações de lançamento, de forma que lançamentos sempre seja possível compilar com novos compiladores que podem ter introduzido mais avisos. Defina seu terceiro parâmetro para “yes” para compilações de lançamento (e apenas compilações de lançamento) para habilitar essa funcionalidade. Compilações de desenvolvimento e de integração contínua (em inglês “continuous integration” ou, abreviado, “CI”) deve sempre ter <code>-Werror</code> habilitado.

note: (itstool) path: section/p
en: Release builds can be detected using the <link href="http://www.gnu.org/software/autoconf-archive/ax_is_release.html"><code>AX_IS_RELEASE</code></link> macro, the result of which can be passed directly to <code>AX_COMPILER_FLAGS</code>:
pt_BR: Compilações de lançamento podem ser detectadas usando a macro <link href="http://www.gnu.org/software/autoconf-archive/ax_is_release.html"><code>AX_IS_RELEASE</code></link>, podendo o seu resultado ser passado diretamente para <code>AX_COMPILER_FLAGS</code>:

note: (itstool) path: section/p
en: The choice of release stability policy (the first argument to <code>AX_IS_RELEASE</code>) should be made per project, taking the project’s <link xref="versioning">versioning stability</link> into account.
pt_BR: A escolha de política de estabilidade de lançamento (o primeiro argumento para <code>AX_IS_RELEASE</code>) deve ser feita por projeto, levando em consideração a <link xref="versioning">estabilidade de versionamento</link> do projeto.

note: (itstool) path: section/p
en: GDB is the standard debugger for C on Linux. Its most common uses are for debugging crashes, and for stepping through code as it executes. A full tutorial for using GDB is given <link href="https://sourceware.org/gdb/current/onlinedocs/gdb/"> here</link>.
pt_BR: GDB é o depurador padrão para C no Linux. Seu uso mais comum é para depurar travamentos, e para analisar o código enquanto ele é executado. Um tutorial completo para usar GDB é fornecido <link href="https://sourceware.org/gdb/current/onlinedocs/gdb/"> aqui</link>.

note: (itstool) path: section/p
en: To run GDB on a program from within the source tree, use: <cmd>libtool exec gdb --args <var>./program-name</var> <var>--some --arguments --here</var></cmd>
pt_BR: Para executar GDB em um programa dentro da árvore fonte, use <cmd>libtool exec gdb --args <var>./nome-do-programa</var> <var>--alguns --argumentos --aqui</var></cmd>

note: (itstool) path: section/p
en: This is necessary due to libtool wrapping each compiled binary in the source tree in a shell script which sets up some libtool variables. It is not necessary for debugging installed executables.
pt_BR: Isso é necessário porque o libtool interfaceia cada binário compilado na árvore fonte em um script shell que define algumas variáveis libtool. Não é necessário para depurar executáveis instalados.

note: (itstool) path: section/p
en: GDB has many advanced features which can be combined to essentially create small debugging scripts, triggered by different breakpoints in code. Sometimes this is a useful approach (for example, for <link href="https://tecnocode.co.uk/2010/07/12/reference-count-debugging-with-gdb/"> reference count debugging</link>), but sometimes simply using <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"> <code>g_debug()</code></link> to output a debug message is simpler.
pt_BR: GDB possui muitos recursos avançados que podem ser combinados para essencialmente criar pequenos scripts de depuração, ativados por diferentes pontos de interrupção no código. Algumas vezes, essa é uma abordagem útil (para <link href="https://tecnocode.co.uk/2010/07/12/reference-count-debugging-with-gdb/">depuração de contagem de referência</link>), mas outras vezes simplesmente usar <link href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#g-debug"> <code>g_debug()</code></link> para emitir uma mensagem de depuração é mais simples.

note: (itstool) path: section/p
en: Valgrind is a suite of tools for instrumenting and profiling programs. Its most famous tool is <link xref="#memcheck">memcheck</link>, but it has several other powerful and useful tools too. They are covered separately in the sections below.
pt_BR: Valgrind é uma suíte de ferramentas para instrumentar e perfilar programas. Sua ferramenta mais famosa é o <link xref="#memcheck">memcheck</link>, mas há, no Valgrind, também várias outras ferramentas poderosas e úteis. Elas são cobertas separadamente nas seções a seguir.

note: (itstool) path: section/p
en: A useful way of running Valgrind is to run a program’s unit test suite under Valgrind, setting Valgrind to return a status code indicating the number of errors it encountered. When run as part of <cmd>make check</cmd>, this will cause the checks to succeed if Valgrind finds no problems, and fail otherwise. However, running <cmd>make check</cmd> under Valgrind is not trivial to do on the command line. A macro, <link href="http://www.gnu.org/software/autoconf-archive/ax_valgrind_check.html"> <code>AX_VALGRIND_CHECK</code></link> can be used which adds a new <cmd>make check-valgrind</cmd> target to automate this. To use it:
pt_BR: Uma forma útil de executar Valgrind é executar uma suíte de teste de unidade do programa sob Valgrind, configurando-o para retornar um código de status indicando o número de erros que ele encontrou. Quando executado como parte de <cmd>make check</cmd>, isso fará com que as verificações tenham sucesso se Valgrind encontrar nenhum problema; do contrário, falhará. Porém, executar <cmd>make check</cmd> sob Valgrind não é algo trivial de se fazer na linha de comando. Uma macro, <link href="http://www.gnu.org/software/autoconf-archive/ax_valgrind_check.html"> <code>AX_VALGRIND_CHECK</code></link> pode ser usada para adicionar um novo alvo <cmd>make check-valgrind</cmd> para automatizar isso. Para usá-lo:

note: (itstool) path: item/p
en: Copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_valgrind_check.m4"> <file>ax_valgrind_check.m4</file></link> to the <file>m4/</file> directory of your project.
pt_BR: Copie <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_valgrind_check.m4"> <file>ax_valgrind_check.m4</file></link> para o diretório <file>m4/</file> de seu projeto.

note: (itstool) path: item/p
en: Add <code>AX_VALGRIND_CHECK</code> to <file>configure.ac</file>.
pt_BR: Adicione <code>AX_VALGRIND_CHECK</code> para <file>configure.ac</file>.

note: (itstool) path: item/p
en: Add <code>@VALGRIND_CHECK_RULES@</code> to the <file>Makefile.am</file> in each directory which contains unit tests.
pt_BR: Adicione <code>@VALGRIND_CHECK_RULES@</code> para o <file>Makefile.am</file> em cada diretório que contém testes de unidade.

note: (itstool) path: section/p
en: When <cmd>make check-valgrind</cmd> is run, it will save its results in <file>test-suite-*.log</file>, one log file per tool. Note that you will need to run it from the directory containing the unit tests.
pt_BR: Quando <cmd>make check-valgrind</cmd> é executado, ele salva seus resultados em <file>test-suite-*.log</file>, um arquivo de registro por ferramenta. Note que você precisará executá-lo a partir de um diretório contendo os testes de unidade.

note: (itstool) path: section/p
en: Valgrind has a way to suppress false positives, by using <link href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress"> suppression files</link>. These list patterns which may match error stack traces. If a stack trace from an error matches part of a suppression entry, it is not reported. For various reasons, GLib currently causes a number of false positives in <link xref="#memcheck">memcheck</link> and <link xref="#helgrind-and-drd">helgrind and drd</link> which must be suppressed by default for Valgrind to be useful. For this reason, every project should use a standard GLib suppression file as well as a project specific one.
pt_BR: Valgrind possui uma forma de suprimir falsos positivos, usando <link href="http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress">arquivos de supressão</link>. Estes listam padrões que pode corresponder a rastros de pilhas de erros. Se um rastro de pilha de um erro corresponde a parte de uma entrada de supressão, ele não é relatado. Por vários motivos, GLib atualmente causa vários falsos positivos no <link xref="#memcheck">memcheck</link> e <link xref="#helgrind-and-drd">helgrind e drd</link>, o que deve ser suprimido por padrão para Valgrind ser útil. Por este motivo, todo projeto deve usar um arquivo de supressão padrão de GLib, bem como um específico do projeto.

note: (itstool) path: section/p
en: Suppression files are supported by the <code>AX_VALGRIND_CHECK</code> macro:
pt_BR: Há suporte a arquivos de supressão na macro <code>AX_VALGRIND_CHECK</code>:

note: (itstool) path: section/code
en: @VALGRIND_CHECK_RULES@
    VALGRIND_SUPPRESSIONS_FILES = my-project.supp glib.supp
    EXTRA_DIST = $(VALGRIND_SUPPRESSIONS_FILES)
pt_BR: @VALGRIND_CHECK_RULES@
    VALGRIND_SUPPRESSIONS_FILES = meu-projeto.supp glib.supp
    EXTRA_DIST = $(VALGRIND_SUPPRESSIONS_FILES)

note: (itstool) path: section/p
en: memcheck is a memory usage and allocation analyzer. It detects problems with memory accesses and modifications of the heap (allocations and frees). It is a highly robust and mature tool, and its output can be entirely trusted. If it says there is ‘definitely’ a memory leak, there is definitely a memory leak which should be fixed. If it says there is ‘potentially’ a memory leak, there may be a leak to be fixed, or it may be memory allocated at initialization time and used throughout the life of the program without needing to be freed.
pt_BR: O memcheck é um analisador de uso e alocação de memória. Ele detecta problemas com acessos e modificações de memória da heap (alocações e liberações). É uma ferramenta altamente robusta e madura, e sua saída pode ser totalmente confiada. Se ele diz que “definitely” é um vazamento de memória, definitivamente há um vazamento de memória que deve ser corrigido. Se ele diz que “potentially” é um vazamento de memória, pode haver um vazamento a ser corrigido, ou pode ser uma memória alocada em tempo de inicialização e usada ao longo da vida do programa sem precisar ser liberada.

note: (itstool) path: section/p
en: To run memcheck manually on an installed program, use:
pt_BR: Para executar memcheck manualmente em um programa instalado, use:

note: (itstool) path: section/p
en: <cmd>valgrind --tool=memcheck --leak-check=full <var>my-program-name</var></cmd>
pt_BR: <cmd>valgrind --tool=memcheck --leak-check=full <var>nome-do-meu-programa</var></cmd>

note: (itstool) path: section/p
en: Or, if running your program from the source directory, use the following to avoid running leak checking on the libtool helper scripts:
pt_BR: Ou, se está executando seu programa a partir do diretório fonte, use o seguinte para evitar a execução de verificação de vazamento em scripts auxiliares do libtool:

note: (itstool) path: section/p
en: <cmd>libtool exec valgrind --tool=memcheck --leak-check=full <var>./my-program-name</var></cmd>
pt_BR: <cmd>libtool exec valgrind --tool=memcheck --leak-check=full <var>./nome-do-meu-programa</var></cmd>

note: (itstool) path: section/p
en: Valgrind lists each memory problem it detects, along with a short backtrace (if you’ve compiled your program with debug symbols), allowing the cause of the memory error to be pinpointed and fixed.
pt_BR: Valgrind lista cada problema de memória que ele detecta, junto com um rastro curto (se você compilou seu programa com símbolos de depuração), permitindo que a causa do erro de memória seja apontada e corrigida.

note: (itstool) path: section/p
en: A full tutorial on using memcheck is <link href="http://valgrind.org/docs/manual/mc-manual.html">here</link>.
pt_BR: Um tutorial completo sobre uso do memcheck está <link href="http://valgrind.org/docs/manual/mc-manual.html">aqui</link>.

note: (itstool) path: section/title
en: cachegrind and KCacheGrind
pt_BR: cachegrind e KCacheGrind

note: (itstool) path: section/p
en: cachegrind is a cache performance profiler which can also measure instruction execution, and hence is very useful for profiling general performance of a program. <link href="http://kcachegrind.sourceforge.net/html/Home.html"> KCacheGrind</link> is a useful UI for it which allows visualization and exploration of the profiling data, and the two tools should rarely be used separately.
pt_BR: cachegrind é um perfilador de desempenho do cache que também pode medir a execução de uma instrução e, portanto, é muito útil para perfilar desempenho em geral de um programa. <link href="http://kcachegrind.sourceforge.net/html/Home.html"> KCacheGrind</link> é uma interface gráfica útil para isso que permite visualização e exploração de dados de perfil, e as ferramentas raramente devem ser usados separadamente.

note: (itstool) path: section/p
en: cachegrind works by simulating the processor’s memory hierarchy, so there are situations where it is <link href="http://valgrind.org/docs/manual/cg-manual.html#cg-manual.annopts.accuracy"> not perfectly accurate</link>. However, its results are always representative enough to be very useful in debugging performance hotspots.
pt_BR: cachegrind funciona simulando a hierarquia de memória do processador, de forma que há situações em que <link href="http://valgrind.org/docs/manual/cg-manual.html#cg-manual.annopts.accuracy">não é perfeitamente acurado</link>. Porém, seu resultado é sempre suficientemente representativo para ser muito útil em depurar pontos de desempenho.

note: (itstool) path: section/p
en: A full tutorial on using cachegrind is <link href="http://valgrind.org/docs/manual/cg-manual.html">here</link>.
pt_BR: Um tutorial completo sobre uso do cachegrind está <link href="http://valgrind.org/docs/manual/cg-manual.html">aqui</link>.

note: (itstool) path: section/title
en: helgrind and drd
pt_BR: helgrind e drd

note: (itstool) path: section/p
en: helgrind and drd are threading error detectors, checking for race conditions in memory accesses, and abuses of the <link href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html"> POSIX pthreads API</link>. They are similar tools, but are implemented using different techniques, so both should be used.
pt_BR: helgrind e drd são detectores de erro em threads, verificações de condições de corrida em acessos de memória e abusos do <link href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html">API pthredas do POSIX</link>. Elas são ferramentas similares, mas são implementadas usando técnicas diferentes, de forma que ambas deveriam ser usadas.

note: (itstool) path: section/p
en: The kinds of errors detected by helgrind and drd are: data accessed from multiple threads without consistent locking, changes in lock acquisition order, freeing a mutex while it is locked, locking a locked mutex, unlocking an unlocked mutex, and several other errors. Each error, when detected, is printed to the console in a little report, with a separate report giving the allocation or spawning details of the mutexes or threads involved so that their definitions can be found.
pt_BR: Os tipos de erros detectados pelo helgrind e drd são: dados acessados por múltiplas threads sem travamento consistente, alterações na ordem de aquisição de trava, liberação um mutex enquanto ele está travado, travamento de um mutex travado, destravamento de um mutex destravado e vários outros erros. Cada erro, quando detectado, é emitido para o console em um pequeno relatório, com um relatório separado fornecendo os detalhes de alocação ou criação de mutexes ou threads envolvidos, de forma que suas definições podem ser localizadas.

note: (itstool) path: section/p
en: helgrind and drd can produce more false positives than memcheck or cachegrind, so their output should be studied a little more carefully. However, threading problems are notoriously elusive even to experienced programmers, so helgrind and drd errors should not be dismissed lightly.
pt_BR: helgrind e drd podem produzir mais falsos positivos que memcheck ou cachegrind, de forma que suas saídas podem ser estudadas com um pouco de cuidado. Porém, problemas em threads são notoriamente elusivos mesmo para programadores mais experientes, de forma que erros de helgrind e drd não devem ser desconsiderados.

note: (itstool) path: section/p
en: Full tutorials on using helgrind and drd are <link href="http://valgrind.org/docs/manual/hg-manual.html">here</link> and <link href="http://valgrind.org/docs/manual/drd-manual.html"> here</link>.
pt_BR: Tutorias completos sobre usar helgrind e drd estão <link href="http://valgrind.org/docs/manual/hg-manual.html">aqui</link> e <link href="http://valgrind.org/docs/manual/drd-manual.html">aqui</link>.

note: (itstool) path: section/p
en: sgcheck is an array bounds checker, which detects accesses to arrays which have overstepped the length of the array. However, it is a very young tool, still marked as experimental, and hence may produce more false positives than other tools.
pt_BR: sgcheck é um verificador de limites de vetor que detecta acessos a vetores que podem ter ultrapassados o tamanho do vetor. Porém, é uma ferramenta muito jovem, ainda marcada como experimental e, portanto, pode produzir muitos mais falsos positivos que outras ferramentas.

note: (itstool) path: section/p
en: As it is experimental, sgcheck must be run by passing <cmd>--tool=exp-sgcheck</cmd> to Valgrind, rather than <cmd>--tool=sgcheck</cmd>.
pt_BR: Por ser experimental, sgcheck deve ser executado passando <cmd>--tool=exp-sgcheck</cmd> para o Valgrind, em vez de <cmd>--tool=sgcheck</cmd>.

note: (itstool) path: section/p
en: A full tutorial on using sgcheck is <link href="http://valgrind.org/docs/manual/sg-manual.html">here</link>.
pt_BR: Um tutorial completo sobre uso do sgcheck está <link href="http://valgrind.org/docs/manual/sg-manual.html">aqui</link>.

note: (itstool) path: section/title
en: gcov and lcov
pt_BR: gcov e lcov

note: (itstool) path: section/p
en: <link href="https://gcc.gnu.org/onlinedocs/gcc/Gcov.html">gcov</link> is a profiling tool built into GCC, which instruments code by adding extra instructions at compile time. When the program is run, this code generates <file>.gcda</file> and <file>.gcno</file> profiling output files. These files can be analyzed by the <cmd>lcov</cmd> tool, which generates visual reports of code coverage at runtime, highlighting lines of code in the project which are run more than others.
pt_BR: <link href="https://gcc.gnu.org/onlinedocs/gcc/Gcov.html">gcov</link> é uma ferramenta de perfilamento construída em GCC que instrumenta código adicionando instruções extras em tempo de compilação. Quando o programa é executado, esse código gera os arquivos de saída de perfilamento <file>.gcda</file> e <file>.gcno</file>. Esses arquivos podem ser analisados pela ferramenta <cmd>lcov</cmd>, que gera relatórios visuais de cobertura de código em tempo de execução, linhas destacadas de código no projeto que executa mais do que outros.

note: (itstool) path: section/p
en: A critical use for this code coverage data collection is when running the unit tests: if the amount of code covered (for example, which particular lines were run) by the unit tests is known, it can be used to guide further expansion of the unit tests. By regularly checking the code coverage attained by the unit tests, and expanding them towards 100%, you can be sure that the entire project is being tested. Often it is the case that a unit test exercises most of the code, but not a particular control flow path, which then harbours residual bugs.
pt_BR: Um uso crítico para essa coleção de dados de cobertura de código é quando se está executando testes de unidade: se a quantidade de código coberto (por exemplo, quais linhas em particular foram executadas) pelos testes de unidade é conhecida, ela pode ser usado para guiar expansões posteriores de testes de unidade. Ao verificar regularmente a cobertura de código atingido pelos testes de unidade e expandindo-os para 100%, você pode se certificar de que todo o projeto está sendo testado. Frequentemente é o caso de que um teste de unidade exercita a maioria do código, mas não um caminho de fluxo de controle em particular, o qual acaba por abrigar erros residuais.

note: (itstool) path: section/p
en: lcov supports <link href="http://en.wikipedia.org/wiki/Code_coverage#Basic_coverage_criteria"> branch coverage measurement</link>, so is not suitable for demonstrating coverage of safety critical code. It is perfectly suitable for non-safety critical code.
pt_BR: lcov oferece suporte a <link href="http://en.wikipedia.org/wiki/Code_coverage#Basic_coverage_criteria">medida de cobertura de ramo</link>, de forma que é seja adequado para demonstrar cobertura de código crítico de segurança. É perfeitamente adequado para código crítico que não seja de segurança.

note: (itstool) path: section/p
en: As code coverage has to be enabled at both compile time and run time, a macro is provided to make things simpler. The <link href="http://www.gnu.org/software/autoconf-archive/ax_code_coverage.html"> <code>AX_CODE_COVERAGE</code></link> macro adds a <cmd>make check-code-coverage</cmd> target to the build system, which runs the unit tests with code coverage enabled, and generates a report using <cmd>lcov</cmd>.
pt_BR: Como a cobertura de código tem que estar habilitada em ambos tempo de compilação de execução, uma macro é fornecida para simplificar as coisas. A macro <link href="http://www.gnu.org/software/autoconf-archive/ax_code_coverage.html"> <code>AX_CODE_COVERAGE</code></link> adiciona um alvo de <cmd>make check-code-coverage</cmd> ao sistema de compilação, o qual executa os testes de unidade com cobertura de código habilitada e gera um relatório usando <cmd>lcov</cmd>.

note: (itstool) path: section/p
en: To add <code>AX_CODE_COVERAGE</code> support to a project:
pt_BR: Para adicionar suporte ao <code>AX_CODE_COVERAGE</code> a um projeto:

note: (itstool) path: item/p
en: Copy <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_code_coverage.m4"> <file>ax_code_coverage.m4</file></link> to the <file>m4/</file> directory of your project.
pt_BR: Copie <link href="http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_code_coverage.m4"> <file>ax_code_coverage.m4</file></link> para o diretório <file>m4/</file> de seu projeto.

note: (itstool) path: item/p
en: Add <code>AX_CODE_COVERAGE</code> to <file>configure.ac</file>.
pt_BR: Adicione <code>AX_CODE_COVERAGE</code> para <file>configure.ac</file>.

note: (itstool) path: item/p
en: Add <code>@CODE_COVERAGE_RULES</code> to the top-level <file>Makefile.am</file>.
pt_BR: Adicione <code>@CODE_COVERAGE_RULES</code> ao <file>Makefile.am</file> de topo de nível.

note: (itstool) path: item/p
en: Add <code>$(CODE_COVERAGE_CFLAGS)</code> to the automake <code><var>*</var>_CFLAGS</code> variable for each target you want coverage for, for example for all libraries but no unit test code. Do the same for <code>$(CODE_COVERAGE_LDFLAGS)</code> and <code><var>*</var>_LDFLAGS</code>.
pt_BR: Adicione <code>$(CODE_COVERAGE_CFLAGS)</code> às variáveis <code><var>*</var>_CFLAGS</code> do automake para cada alvo ao qual você deseja cobertura, por exemplo para todas bibliotecas com nenhum código de teste de unidade. Faça o mesmo para <code>$(CODE_COVERAGE_LDFLAGS)</code> e <code><var>*</var>_LDFLAGS</code>.

note: (itstool) path: section/p
en: Documentation on using gcov and lcov is <link href="http://ltp.sourceforge.net/coverage/lcov.php">here</link>.
pt_BR: A documentação sobre o uso de gcov e lcov está <link href="http://ltp.sourceforge.net/coverage/lcov.php">aqui</link>.

note: (itstool) path: section/title
en: Address, Thread and Undefined Behavior Sanitizers
pt_BR: Sanitizadores de endereço, thread e comportamentos indefinidos

note: (itstool) path: section/p
en: GCC and Clang both support several sanitizers: sets of extra code and checks which can be optionally compiled in to an application and used to flag various incorrect behaviors at runtime. They are powerful tools, but have to be enabled specially, recompiling your application to enable and disable them. They cannot be enabled at the same time as each other, or used at the same time as <link xref="#valgrind">Valgrind</link>. They are still young, so have little integration with other tooling.
pt_BR: GCC e Clang oferecem suporte a vários sanitizadores: conjuntos de código extra e verificações que opcionalmente podem ser compilados nele para um aplicativo e usado para sinalizar vários comportamentos incorretos em tempo de execução. Elas são ferramentas poderosas, mas em especial têm que estar habilitadas, recompilando seu aplicativo para habilitá-los e desabilitá-los. Eles não podem estar habilitados ao mesmo tempo que um ao outro, ou usado ao mesmo tempo que <link xref="#valgrind">Valgrind</link>. Eles ainda estão jovens, então possuem pouca integração com outras ferramentarias.

note: (itstool) path: section/p
en: All sanitizers are available for both GCC and Clang, accepting the same set of compiler options.
pt_BR: Todos os sanitizadores estão disponíveis para GCC e Clang, aceitando o mesmo conjunto de opções de compilador.

note: (itstool) path: section/title
en: Address Sanitizer
pt_BR: Sanitizador de endereço

note: (itstool) path: section/p
en: The <link href="https://code.google.com/p/address-sanitizer/">address sanitizer</link> (‘asan’) detects use-after-free and buffer overflow bugs in C and C++ programs. A full tutorial on using asan is <link href="http://clang.llvm.org/docs/AddressSanitizer.html#usage">available for Clang</link> — the same instructions should work for GCC.
pt_BR: Também conhecido como “<link href="https://code.google.com/p/address-sanitizer/">address sanitizer</link>” (“asan”), ele detecta erros de uso-após-liberação e estouro de buffer em programas C e C++. Um tutorial completo sobre o uso de asan está <link href="http://clang.llvm.org/docs/AddressSanitizer.html#usage">disponível para Clang</link> — as mesmas instruções devem funcionar para GCC.

note: (itstool) path: section/title
en: Thread Sanitizer
pt_BR: Sanitizador de thread

note: (itstool) path: section/p
en: The <link href="https://code.google.com/p/thread-sanitizer/">thread sanitizer</link> (‘tsan’) detects data races on memory locations, plus a variety of invalid uses of POSIX threading APIs. A full tutorial on using tsan is <link href="http://clang.llvm.org/docs/ThreadSanitizer.html#usage">available for Clang</link> — the same instructions should work for GCC.
pt_BR: Também chamado de “<link href="https://code.google.com/p/thread-sanitizer/">thread sanitizer</link>” (“tsan”), ele detecta corridas de dados em localizações de memória, além de uma variedade de usos inválidos de APIs de thread do POSIX. Um tutorial completo sobre o uso de tsan está <link href="http://clang.llvm.org/docs/ThreadSanitizer.html#usage">disponível para Clang</link> — as mesmas instruções devem funcionar para GCC.

note: (itstool) path: section/title
en: Undefined Behavior Sanitizer
pt_BR: Sanitizador de comportamento indefinido

note: (itstool) path: section/p
en: The undefined behavior sanitizer (‘ubsan’) is a collection of smaller instrumentations which detect various potentially undefined behaviors in C programs. A set of instructions for enabling ubsan is <link href="http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation">available for Clang</link> — the same instructions should work for GCC.
pt_BR: Também chamado de “undefined behavior sanitizer” (“ubsan”), ele é uma coleção de instrumentações menores que detectam vários comportamentos indefinidos em potencial em programas C. Um conjunto de instruções para habilitar ubsan está <link href="http://clang.llvm.org/docs/UsersManual.html#controlling-code-generation">disponível para Clang</link> — as mesmas instruções devem funcionar para o GCC.

note: (itstool) path: section/p
en: <link href="http://scan.coverity.com/">Coverity</link> is one of the most popular and biggest commercial static analyzer tools available. However, it is available to use free for Open Source projects, and any project is encouraged to <link href="https://scan.coverity.com/users/sign_up">sign up</link>. <link href="https://scan.coverity.com/faq#how-get-project-included-in-scan"> Analysis is performed</link> by running some analysis tools locally, then uploading the source code and results as a tarball to Coverity’s site. The results are then visible online to members of the project, as annotations on the project’s source code (similarly to how lcov presents its results).
pt_BR: <link href="http://scan.coverity.com/">Coverity</link> é uma das maiores e mais populares ferramentas comerciais de análise estática disponível. Porém, está disponível para uso para projetos de código aberto e qualquer projeto é encorajado a <link href="https://scan.coverity.com/users/sign_up">se inscrever</link>. A <link href="https://scan.coverity.com/faq#how-get-project-included-in-scan"> análise é realizada</link> executando algumas ferramentas de análise localmente e, então, enviando o código-fonte e resultados como um tarball para o site do Coverity. Os resultados ficam, então, visíveis online para todos os membros do projeto, como anotações do código-fonte do projeto (similarmente a como lconv apresenta seus resultados).

note: (itstool) path: section/p
en: As Coverity cannot be run entirely locally, it cannot be integrated properly into the build system. However, scripts do exist to automatically scan a project and upload the tarball to Coverity regularly. The recommended approach is to run these scripts regularly on a server (typically as a cronjob), using a clean checkout of the project’s git repository. Coverity automatically e-mails project members about new static analysis problems it finds, so the same approach as for <link xref="#gcc-and-clang">compiler warnings</link> can be taken: eliminate all the static analysis warnings, then eliminate new ones as they are detected.
pt_BR: Como o Coverity não pode ser executado inteiramente localmente, ele não pode ser integrado apropriadamente no sistema de compilação. Porém, scripts existem para varrer automaticamente um projeto e enviar o tarball periodicamente para Coverity. A abordagem recomendada é executar esses scripts periodicamente em um servidor (geralmente como um cronjob), usando um checkout limpo do repositório git do projeto. Coverity automaticamente envia e-mail para membros do projeto sobre novos problemas na análise estática que forem encontrados, de forma que a mesma abordagem que os <link xref="#gcc-and-clang">avisos de compilador</link> possam ser levados: elmitar todos os avisos de análise estática

note: (itstool) path: section/p
en: Coverity is good, but it is not perfect, and it does produce a number of false positives. These should be marked as ignored in the online interface.
pt_BR: Coverity é bom, mas não é perfeito e produz um número de falsos positivos. Esses devem ser marcados como ignorados na interface online.

note: (itstool) path: section/title
en: Clang Static Analyzer
pt_BR: Analisador estático do Clang

note: (itstool) path: section/p
en: One tool which can be used to perform static analysis locally is the <link href="http://clang-analyzer.llvm.org/">Clang static analyzer</link>, which is a tool co-developed with the <link xref="#gcc-and-clang">Clang compiler</link>. It detects a variety of problems in C code which compilers cannot, and which would otherwise only be detectable at run time (using unit tests).
pt_BR: Uma ferramenta que pode ser usada para realizar análise estática localmente é o <link href="http://clang-analyzer.llvm.org/">analisador estático do Clang</link>, que é uma ferramenta co-desenvolvida com o <link xref="#gcc-and-clang">compilador Clang</link>. Ele detecta uma variedade de problemas no código C que compiladores não conseguem, e que, do contrário, seria detectável apenas em tempo de execução (usando testes de unidade).

note: (itstool) path: section/p
en: Clang produces some false positives, and there is no easy way to ignore them. The recommended thing to do is to <link href="http://clang-analyzer.llvm.org/faq.html#suppress_issue">file a bug report against the static analyzer</link>, so that the false positive can be fixed in future.
pt_BR: Clang produz alguns falsos positivos e não há uma forma fácil de ignorá-los. O recomendado é <link href="http://clang-analyzer.llvm.org/faq.html#suppress_issue">preencher um relatório de erro para o analisador estático</link>, de forma que o falso positivo possa ser corrigido no futuro.

note: (itstool) path: section/p
en: A full tutorial on using Clang is <link href="http://clang-analyzer.llvm.org/scan-build.html">here</link>.
pt_BR: Um tutorial completo sobre o uso Clang está <link href="http://clang-analyzer.llvm.org/scan-build.html">aqui</link>.

note: (itstool) path: section/p
en: However, for all the power of the Clang static analyzer, it cannot detect problems with specific libraries, such as GLib. This is a problem if a project uses GLib exclusively, and rarely uses POSIX APIs (which Clang does understand). There is a plugin available for the Clang static analyzer, called <link href="http://people.collabora.com/~pwith/tartan/">Tartan</link>, which extends Clang to support checks against some of the common GLib APIs.
pt_BR: Porém, apesar de todos os poderes do analisador estático do Clang, ele não pode detectar problemas com bibliotecas específicas, como o GLib. Isso é um problema, se um projeto usa exclusivamente o GLib, e raramente usa APIs do POSIX (o qual Clang entende). Há um plug-in disponível para o analisador estático do Clang, chamado <link href="http://people.collabora.com/~pwith/tartan/">Tartan</link>, que estende o Clang de forma a oferecer suporte a verificações de algumas das APIs comuns do GLib.

note: (itstool) path: section/p
en: Tartan is still young software, and will produce false positives and may crash when run on some code. However, it can find legitimate bugs quite quickly, and is worth running over a code base frequently to detect new errors in the use of GLib in the code. Please <link href="http://people.collabora.com/~pwith/tartan/#troubleshooting"> report any problems with Tartan</link>.
pt_BR: Tartan ainda é um software jovem, então ele produzirá falsos positivos e pode travar quando executado em algum código. Porém, ele pode localizar erros legítimos bem rapidamente, e compensa executar frequentemente sobre um código base para detectar novos erros no uso do GLib no código. Por favor, <link href="http://people.collabora.com/~pwith/tartan/#troubleshooting"> relate quaisquer problemas com Tartan</link>.

note: (itstool) path: section/p
en: A full tutorial on enabling Tartan for use with the Clang static analyzer is <link href="http://people.collabora.com/~pwith/tartan/#usage-standalone"> here</link>. If set up correctly, the output from Tartan will be mixed together with the normal static analyzer output.
pt_BR: Um tutorial completo sobre habilitar Tartan para uso com o analisador estático do Clang está <link href="http://people.collabora.com/~pwith/tartan/#usage-standalone"> aqui</link>. Se configurado corretamente, a saída do Tartan será misturada com a saída normal do analisador estático.

note: (itstool) path: info/desc
en: Designing software to be tested and writing unit tests for it
pt_BR: Projete software para ser testado e escreva testes de unidades para ele

note: (itstool) path: page/title
en: Unit Testing
pt_BR: Teste de unidade

note: (itstool) path: synopsis/p
en: Unit testing should be the primary method of testing the bulk of code written, because a unit test can be written once and run many times — manual tests have to be planned once and then manually run each time.
pt_BR: Teste de unidade deve ser o método principal para testar o conjunto de código escrito porque um teste de unidade pode ser escrito uma vez e executado muitas outras — testes manuais têm que ser planejados uma vez e, então, executado manualmente cada vez.

note: (itstool) path: synopsis/p
en: Development of unit tests starts with the architecture and API design of the code to be tested: code should be designed to be easily testable, or will potentially be very difficult to test.
pt_BR: O desenvolvimento de testes de unidade se inicia com o design de API e arquitetura do código a ser testado: o código deve ser projetado para ser facilmente testável, do contrário provavelmente ele será muito difícil de testar.

note: (itstool) path: item/p
en: Write unit tests to be as small as possible, but no smaller. (<link xref="#writing-unit-tests"/>)
pt_BR: Escreva testes de unidade para serem tão pequenos quanto possível, mas não menores. (<link xref="#writing-unit-tests"/>)

note: (itstool) path: item/p
en: Use code coverage tools to write tests to get high code coverage. (<link xref="#writing-unit-tests"/>)
pt_BR: Use ferramentas de cobertura de código para escrever testes para obter alta cobertura de código. (<link xref="#writing-unit-tests"/>)

note: (itstool) path: item/p
en: Run all unit tests under Valgrind to check for leaks and other problems. (<link xref="#leak-checking"/>)
pt_BR: Execute todos os testes de unidade sob Valgrind para verificar ocorrências vazamentos e outros problemas. (<link xref="#leak-checking"/>)

note: (itstool) path: item/p
en: Use appropriate tools to automatically generate unit tests where possible. (<link xref="#test-generation"/>)
pt_BR: Use as ferramentas apropriadas para automaticamente gerar testes de unidade onde for possível. (<link xref="#test-generation"/>)

note: (itstool) path: item/p
en: Design code to be testable from the beginning. (<link xref="#writing-testable-code"/>)
pt_BR: Projete o código para ser testável desde o início. (<link xref="#writing-testable-code"/>)

note: (itstool) path: section/title
en: Writing Unit Tests
pt_BR: Escrevendo testes de unidade

note: (itstool) path: section/p
en: Unit tests should be written in conjunction with looking at <link xref="tooling#gcov-and-lcov">code coverage information gained from running the tests</link>. This typically means writing an initial set of unit tests, running them to get coverage data, then reworking and expanding them to increase the code coverage levels. Coverage should be increased first by ensuring all functions are covered (at least in part), and then by ensuring all lines of code are covered. By covering functions first, API problems which will prevent effective testing can be found quickly. These typically manifest as internal functions which cannot easily be called from unit tests. Overall, coverage levels of over 90% should be aimed for; don’t just test cases covered by project requirements, test everything.
pt_BR: Testes de unidade devem ser escritos em conjunto com a análise das <link xref="tooling#gcov-and-lcov">informações de cobertura de código obtidas por executar os testes</link>. Geralmente isso significa escrever um conjunto inicial de testes de unidade, executando-os para obter dados de cobertura e, então, retrabalhar e expandi-los para aumentar os níveis de cobertura de código. A cobertura deve primeiro ser aumentada se certificando de que todas as funções estejam cobertas (pelo menos em parte) e, então, se certificando de que todas as linhas de código estejam cobertas. Ao cobrir as funções primeiro, problemas de API que vão evitar testes efetivos serão localizados rapidamente. Essas geralmente se manifestam como funções internas que não podem ser facilmente chamadas a partir de testes de unidade. Em geral, deve-se ter como meta os níveis de cobertura em cerca de 90%; não teste apenas os casos cobertos pelos requerimentos do projeto, teste tudo.

note: (itstool) path: section/p
en: Like <link xref="version-control">git commits</link>, each unit test should be ‘as small as possible, but no smaller’, testing a single specific API or behavior. Each test case must be able to be run individually, without depending on state from other test cases. This is important to allow debugging of a single failing test, without having to step through all the other test code as well. It also means that a single test failure can easily be traced back to a specific API, rather than a generic ‘unit tests failed somewhere’ message.
pt_BR: Assim como <link xref="version-control">git commits</link>, os testes de unidade devem ser “tão pequenos quanto possível, mas não menores”, testando especificamente uma única API ou um único comportamento. Cada caso de teste deve ser capaz de executar individualmente, sem depender do estado de outros casos de teste. Isso é importante para permitir depuração de falha em um teste, sem ter que também passar por todos os outros códigos de teste. Isso significa que a falha de um teste pode ser facilmente rastreada a uma API específica, em vez de uma mensagem genérica “testes de unidade falharam em algum lugar”.

note: (itstool) path: section/p
en: GLib has support for unit testing with its <link href="https://developer.gnome.org/glib/stable/glib-Testing.html">GTest framework</link>, allowing tests to be arranged in groups and hierarchies. This means that groups of related tests can be run together for enhanced debugging too, by running the test binary with the <cmd>-p</cmd> argument: <cmd>./test-suite-name -p /path/to/test/group</cmd>.
pt_BR: O GLib oferece suporte a testes de unidade com seu <link href="https://developer.gnome.org/glib/stable/glib-Testing.html">framework GTest</link>, permitindo que os testes sejam organizados em grupos e hierarquias. Isso significa que os grupos de testes relacionados podem ser executados juntos para melhorar a depuração também, executando o binário de teste com o argumento <cmd>-p</cmd>: <cmd>./test-suite-nome -p /caminho/para/grupo/de/teste</cmd>.

note: (itstool) path: section/title
en: Installed Tests
pt_BR: Testes instalados

note: (itstool) path: section/p
en: All unit tests should be installed system-wide, following the <link href="https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests">installed-tests standard</link>.
pt_BR: Todos os testes de unidade devem ser instalados para todo o sistema, seguindo o <link href="https://wiki.gnome.org/Initiatives/GnomeGoals/InstalledTests">padrão de testes instalados</link>.

note: (itstool) path: section/p
en: By installing the unit tests, continuous integration (CI) is made easier, since tests for one project can be re-run after changes to other projects in the CI environment, thus testing the interfaces between modules. That is useful for a highly-coupled set of projects like GNOME.
pt_BR: Ao instalar os testes de unidade, integração contínua (CI) é facilitada, já que os testes para um projeto podem ser reexecutados após alterações em outros projetos no ambiente de CI, de forma a testar as interfaces entre módulos. Isso é útil para um conjunto altamente encaixado de projetos como o GNOME.

note: (itstool) path: section/p
en: To add support for installed-tests, add the following to <file>configure.ac</file>:
pt_BR: Para adicionar suporte para testes instalados, adicione o seguinte ao <file>configure.ac</file>:

note: (itstool) path: section/code
en: # Installed tests
    AC_ARG_ENABLE([modular_tests],
                  AS_HELP_STRING([--disable-modular-tests],
                                 [Disable build of test programs (default: no)]),,
                  [enable_modular_tests=yes])
    AC_ARG_ENABLE([installed_tests],
                  AS_HELP_STRING([--enable-installed-tests],
                                 [Install test programs (default: no)]),,
                  [enable_installed_tests=no])
    AM_CONDITIONAL([BUILD_MODULAR_TESTS],
                   [test "$enable_modular_tests" = "yes" ||
                    test "$enable_installed_tests" = "yes"])
    AM_CONDITIONAL([BUILDOPT_INSTALL_TESTS],[test "$enable_installed_tests" = "yes"])
pt_BR: # Testes instalados
    AC_ARG_ENABLE([modular_tests],
                  AS_HELP_STRING([--disable-modular-tests],
                                 [Disable build of test programs (default: no)]),,
                  [enable_modular_tests=yes])
    AC_ARG_ENABLE([installed_tests],
                  AS_HELP_STRING([--enable-installed-tests],
                                 [Install test programs (default: no)]),,
                  [enable_installed_tests=no])
    AM_CONDITIONAL([BUILD_MODULAR_TESTS],
                   [test "$enable_modular_tests" = "yes" ||
                    test "$enable_installed_tests" = "yes"])
    AM_CONDITIONAL([BUILDOPT_INSTALL_TESTS],[test "$enable_installed_tests" = "yes"])

note: (itstool) path: section/p
en: Then in <file>tests/Makefile.am</file>:
pt_BR: Então, em <file>tests/Makefile.am</file>:

note: (itstool) path: section/title
en: Leak Checking
pt_BR: Verificação de vazamento

note: (itstool) path: section/p
en: Once unit tests with high code coverage have been written, they can be run under various dynamic analysis tools, such as <link xref="tooling#valgrind">Valgrind</link> to check for leaks, threading errors, allocation problems, etc. across the entire code base. The higher the code coverage of the unit tests, the more confidence the Valgrind results can be treated with. See <link xref="tooling"/> for more information, including build system integration instructions.
pt_BR: Assim que os testes de unidade com alta cobertura de código forem escritos, eles podem ser executados sob várias ferramentas de análise dinâmica, tal como <link xref="tooling#valgrind">Valgrind</link> para verificar por vazamentos, erros de threading, problemas de alocação, etc. por toda a base de código. Quanto maior a cobertura de código dos testes unitários, mais confiança haverá nos resultados do Valgrind. Veja <link xref="tooling"/> para mais informações, incluindo instruções sobre integração de sistema de compilação.

note: (itstool) path: section/p
en: Critically, this means that unit tests should not leak memory or other resources themselves, and similarly should not have any threading problems. Any such problems would effectively be false positives in the analysis of the actual project code. (False positives which need to be fixed by fixing the unit tests.)
pt_BR: Mais importante de tudo é que isso significa que os testes de unidade não devem eles mesmos resultar em vazamento de memória ou de outros recursos e, de forma similar, não devem ter qualquer problemas de threading. Qualquer um desses problemas seria efetivamente um falso positivo na análise do código projeto. (Falsos positivos que precisam ser resolvidos corrigindo os testes de unidade.)

note: (itstool) path: section/title
en: Test Generation
pt_BR: Geração de testes

note: (itstool) path: section/p
en: Certain types of code are quite repetitive, and require a lot of unit tests to gain good coverage; but are appropriate for <link href="http://en.wikipedia.org/wiki/Test_data_generation">test data generation</link>, where a tool is used to automatically generate test vectors for the code. This can drastically reduce the time needed for writing unit tests, for code in these specific domains.
pt_BR: Certos tipos de códigos são bem repetitivos e exigem muitos testes de unidade para obter uma boa cobertura de código; mas são apropriados para <link href="http://en.wikipedia.org/wiki/Test_data_generation">geração de dados de teste</link>, na qual uma ferramenta é usada para automaticamente gerar vetores de teste para o código. Isso pode reduzir drasticamente o tempo necessário para escrever testes de unidade, para código nesses domínio em específico.

note: (itstool) path: section/p
en: One example of a domain amenable to test data generation is parsing, where the data to be parsed is required to follow a strict schema — this is the case for XML and JSON documents. For JSON, a tool such as <link href="http://people.collabora.com/~pwith/walbottle/">Walbottle</link> can be used to generate test vectors for all types of valid and invalid input according to the schema.
pt_BR: Um exemplo de um domínio acessível para geração de dados de teste é análise, na qual exige-se que os dados a serem analisados sigam um esquema estrito — esse é o caso para documentos XML e JSON. Para JSON, uma ferramenta como <link href="http://people.collabora.com/~pwith/walbottle/">Walbottle</link> pode ser usado para gerar vetores de teste para todos tipos de entrada válida e inválida de acordo com o esquema.

note: (itstool) path: section/p
en: Every type of JSON document should have a <link href="http://json-schema.org/">JSON Schema</link> defined for it, which can then be passed to Walbottle to generate test vectors:
pt_BR: Todo tipo de documento JSON deve ter um <link href="http://json-schema.org/">JSON Schema</link> definido para ele, que pode então ser passado para Walbottle para gerar vetores de teste:

note: (itstool) path: section/p
en: These test vectors can then be passed to the code under test in its unit tests. The JSON instances generated by <cmd>--valid-only</cmd> should be accepted; those from <cmd>--invalid-only</cmd> should be rejected.
pt_BR: Esses vetores de teste podem, então, ser passados para o código sob teste em seus testes de unidade. As instâncias JSON geradas por <cmd>--valid-only</cmd> deve ser aceita; aqueles de <cmd>--invalid-only</cmd> deve ser rejeitado.

note: (itstool) path: section/title
en: Writing Testable Code
pt_BR: Escrevendo código testável

note: (itstool) path: section/p
en: Code should be written with testability in mind from the design stage, as it affects API design and architecture in fundamental ways. A few key principles:
pt_BR: O código deve ser escrito com testabilidade em mente desde o estágio de design, já que isso afeta o design de API e arquitetura em formas fundamentais. Alguns princípios chaves:

note: (itstool) path: item/p
en: Do not use global state. Singleton objects are usually a bad idea as they can’t be instantiated separately or controlled in the unit tests.
pt_BR: Não use um estado global. Objetos “sigleton” são geralmente uma má ideia, pois eles não podem ser instanciados separadamente ou controlados nos testes de unidade.

note: (itstool) path: item/p
en: Separate out use of external state, such as databases, networking, or the file system. The unit tests can then replace the accesses to external state with mocked objects. A common approach to this is to use dependency injection to pass a file system wrapper object to the code under test. For example, a class should not load a global database (from a fixed location in the file system) because the unit tests would then potentially overwrite the running system’s copy of the database, and could never be executed in parallel. They should be passed an object which provides an interface to the database: in a production system, this would be a thin wrapper around the database API; for testing, it would be a mock object which checks the requests given to it and returns hard-coded responses for various tests.
pt_BR: Separe o uso de estado externo, tal como banco de dados, conectividade ou sistema de arquivos. Os testes de unidade podem, então, substituir os acessos a estado externo com objetos simulados (mock). Uma abordagem comum a isso é usar injeção de dependência para passar um objeto interfaceador de sistema de arquivos para o código sob teste. Por exemplo, uma classe não deve carregar um banco de dados global (de uma localização fixa no sistema de arquivos) porque os testes de unidade poderiam acabar sobrescrevendo a cópia do sistema em execução do banco de dados, e nunca poderia ser executado em paralelo. A eles deve ser passado um objeto que fornece uma interface para o banco de dados: em um sistema de produção, isso seria um interfaceador magro em volta da API de banco de dados; para teste, seria um objeto simulado que verifica as requisições fornecidas a ele e retorna respostas codificadas para vários testes.

note: (itstool) path: item/p
en: Expose utility functions where they might be generally useful.
pt_BR: Exponha funções utilitárias onde geralmente elas podem ser úteis.

note: (itstool) path: item/p
en: Split projects up into collections of small, private libraries which are then linked together with a minimal amount of glue code into the overall executable. Each can be tested separately.
pt_BR: Divida projetos em coleções de bibliotecas pequenas e privadas, que são então vinculadas com uma quantidade mínima de código colante no executável global.

note: (itstool) path: section/p
en: The topic of software testability is covered in the following articles:
pt_BR: O tópico de estabilidade de API é coberto nos seguintes artigos (em inglês):

note: (itstool) path: item/p
en: <link href="http://msdn.microsoft.com/en-us/magazine/dd263069.aspx">Design for testability</link>
pt_BR: <link href="http://msdn.microsoft.com/en-us/magazine/dd263069.aspx">Design por testabilidade</link>

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Software_testability">Software testability</link>
pt_BR: <link href="http://en.wikipedia.org/wiki/Software_testability">testabilidade de software</link>

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Dependency_injection">Dependency injection</link>
pt_BR: <link href="http://en.wikipedia.org/wiki/Dependency_injection">Injeção de dependência</link>

note: (itstool) path: item/p
en: <link href="http://c2.com/cgi/wiki?SoftwareDesignForTesting">Software design for testing</link>
pt_BR: <link href="http://c2.com/cgi/wiki?SoftwareDesignForTesting">Design de software para teste</link>

note: (itstool) path: info/desc
en: Source code version control with git
pt_BR: Controle de versão de código-fonte com git

note: (itstool) path: page/title
en: Version Control
pt_BR: Controle de versão

note: (itstool) path: synopsis/p
en: git is used for version control for all GNOME projects. This page assumes good working knowledge of git; some introductory material is available <link href="https://www.atlassian.com/git/tutorials/">here</link>, and a <link href="https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf">git cheatsheet is here</link>.
pt_BR: git é usado para controle de versão para todos os projetos do GNOME. Essa página presume que tenha um bom conhecimento em trabalhar com git; algum material introdutório está disponível <link href="https://www.atlassian.com/git/tutorials/">aqui</link> e um <link href="https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf">folha de dica está aqui</link>.

note: (itstool) path: item/p
en: Make atomic, revertable commits. (<link xref="#guidelines-for-making-commits"/>)
pt_BR: Faça commits atômicos e reversíveis. (<link xref="#guidelines-for-making-commits"/>)

note: (itstool) path: item/p
en: Include full reasoning in commit messages, plus links to relevant bug reports or specifications. (<link xref="#guidelines-for-making-commits"/>)
pt_BR: Inclua toda a fundamentação nas mensagens de commit, junto com links para especificações e relatórios de erros relevantes. (<link xref="#guidelines-for-making-commits"/>)

note: (itstool) path: item/p
en: Keep large changes, such as renames, in separate commits. (<link xref="#guidelines-for-making-commits"/>)
pt_BR: Mantenha alterações grandes, como renomeações, em commits separados. (<link xref="#guidelines-for-making-commits"/>)

note: (itstool) path: item/p
en: Merge changes from feature branches by rebasing. (<link xref="#use-of-git"/>)
pt_BR: Mescle alterações de ramos de recursos por meio de rebase. (<link xref="#use-of-git"/>)

note: (itstool) path: section/title
en: Use of Git
pt_BR: Uso do Git

note: (itstool) path: section/p
en: Most GNOME repositories follow these rules:
pt_BR: A maioria dos repositórios do GNOME seguem essas regras:

note: (itstool) path: item/p
en: No forced pushes. Except for branches with the <code>wip/</code> prefix (work-in-progress), the commits’ history must not be modified, as contributors rely on it.
pt_BR: Nenhum push forçado. Exceto para ramos com o prefixo <code>wip/</code> (trabalho em progress), o histórico de commits não deve ser modificado, pois contribuidores dependem dele.

note: (itstool) path: item/p
en: Rebase commits rather than merging, to have a linear history (which is easier to follow).
pt_BR: Faça rebase nos commits em vez de merge, para ter um histórico linear (que é mais fácil de seguir).

note: (itstool) path: item/p
en: Work on feature branches on GNOME git in <code>wip/</code> branches, then rebase on master and fast-forward merge the changes. It is a good practice to also add your nickname to the branch name, as <code>wip/nickname/feature</code>.
pt_BR: Trabalhe em ramos de recursos no git do GNOME em ramos <code>wip/</code> e então aplique rebase no master e merge em fast-foward nas alterações. Também é uma boa prática adicionar seu apelido ao nome do ramo, como <code>wip/apelido/recurso</code>.

note: (itstool) path: item/p
en: Hide <link href="https://sethrobertson.github.io/GitBestPractices/#sausage">sausage making</link> by squashing commits before merging.
pt_BR: Oculte “<link href="https://sethrobertson.github.io/GitBestPractices/#sausage">fazimento de salsicha</link>” (do inglês, “sausage making”) compactando commits antes de mesclá-los.

note: (itstool) path: section/title
en: Guidelines for Making Commits
pt_BR: Diretrizes para fazer commits

note: (itstool) path: section/p
en: Commits should be as small as possible, but no smaller. Each commit should address a single issue, containing only changes related to that issue. The message for each commit should describe the issue, explain what causes it, and explain how it has been fixed if it is not obvious. If the commit is associated with a bug report, the full URI for the bug report should be put on a line by itself at the bottom of the commit message. Similarly, the ID for the git commit (from <cmd>git log --oneline</cmd>) should be copied into the bug report once the commit has been pushed, so it is easy to find one from the other.
pt_BR: Commits devem ser tão pequenos quanto possível, mas não menores. Cada commit deve resolver um único problema, contendo apenas alterações relacionadas àquele problema. A mensagem para cada commit deve descrever o problema, explicar o que o causa e explicar como ele foi corrigido, se isso não foi óbvio. Se o commit está associado com um relatório de erro, a URI completa para o relatório de erro deve ser colocado em uma linha dedicada na parte inferior da mensagem de commit. Similarmente, o ID para o commit do git (do <cmd>git log --oneline</cmd>) deve ser compiado para o relatório de erro uma vez que o commit tenha sido enviado, com push, de forma que seja fácil localizar um por meio do outro.

note: (itstool) path: section/p
en: The changes in each commit should be easy to read. For example, they should not unnecessarily change whitespace or indentation. Large, mechanical changes, such as renaming a file or function, should be put in separate commits from modifications to code inside that file or function, so that the latter changes do not get buried and lost in the former.
pt_BR: As alterações em cada commit devem ser fáceis de ler. Por exemplo, eles não devem desnecessariamente alterar espaços em branco e recuo. Alterações grandes e mecânicas, tal como renomear um arquivo ou função, devem ser colocadas em commits separados das modificações do código dentro daquele arquivo ou função, de forma que as alterações posteriores não sejam enterradas ou perdidas na anterior.

note: (itstool) path: section/p
en: The following principles give the reasoning for all the advice above:
pt_BR: Os princípios a seguir fundamentam todos os conselhos acima:

note: (itstool) path: item/p
en: Each commit should take the repository from one working state to another, otherwise <link href="http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git#Binary-Search">bisection</link> is impossible.
pt_BR: Cada commit deve levar o repositório a partir de um estado de trabalho para outro, do contrário <link href="http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git#Binary-Search">bissecção</link> é impossível.

note: (itstool) path: item/p
en: Each commit should be individually revertable. If it later turns out that the commit was a bad idea, <cmd>git revert <var>commit ID</var></cmd> should take the repository from a working state to another working state.
pt_BR: Cada commit deve ser individualmente reversível. Se posteriormente o commit acabar sendo uma ideia ruim, <cmd>git revert <var>ID do commit</var></cmd> deve levar o repositório de um estado de trabalho para outro.

note: (itstool) path: item/p
en: The reasoning for each commit, and its relationship to external resources like specifications and bug reports, should be clear, to the extent that commits written by one developer a year in the past should still be understandable by a second developer without having to trace through the changes and work out what they do.
pt_BR: A fundamentação de cada commit, e sua relação com recursos externos como especificações e relatórios de erro, deve estar clara de forma que aqueles commits escritos por um desenvolvedor no passado devem ainda ser entendíveis por um segundo desenvolvedor sem ter que seguir todo rastro de alterações e descobrir o que eles fazem.

note: (itstool) path: item/p
en: Each commit should be written once, and designed to be read many times, by many reviewers and future programmers.
pt_BR: Cada commit deve ser escrito uma vez e projetado para ser lido muitas vezes, por muitos revisores e futuros programadores.

note: (itstool) path: section/title
en: Merging Procedure
pt_BR: Procedimento de mesclagem

note: (itstool) path: section/p
en: To merge a feature branch named <code>my-branch</code> into master, use the following commands:
pt_BR: Para mesclar um ramo de recursos chamado <code>meu-ramo</code> no master, use os seguintes comandos:

note: (itstool) path: section/code
en: 
    git checkout master
    git pull
    
    git checkout wip/<var>my-branch</var>
    git rebase --interactive master
    # Ensure the rebase is successful; test the changes
    
    git checkout master
    git merge wip/<var>my-branch</var>
    git push
    
    # wip/<var>my-branch</var> can now be deleted
    git push origin :wip/<var>my-branch</var>
    git branch -D wip/<var>my-branch</var>
pt_BR: 
    git checkout master
    git pull
    
    git checkout wip/<var>meu-ramo</var>
    git rebase --interactive master
    # Certifique-se que o rebase funcione com sucesso; teste as alterações
    
    git checkout master
    git merge wip/<var>meu-ramo</var>
    git push
    
    # wip/<var>meu-ramo</var> agora pode ser excluído
    git push origin :wip/<var>meu-ramo</var>
    git branch -D wip/<var>meu-ramo</var>

note: (itstool) path: item/p
en: <link href="https://sethrobertson.github.io/GitBestPractices/">Git best practices</link>
pt_BR: <link href="https://sethrobertson.github.io/GitBestPractices/">Melhores práticas com git</link>

note: (itstool) path: item/p
en: <link href="https://help.github.com/categories/using-git/">Git FAQ</link>
pt_BR: <link href="https://help.github.com/categories/using-git/">Perguntas frequentes do git</link>

note: (itstool) path: item/p
en: <link href="https://www.atlassian.com/git/tutorials/">Atlassian git tutorial</link>
pt_BR: <link href="https://www.atlassian.com/git/tutorials/">Tutorial de git do Atlassian</link>

note: (itstool) path: item/p
en: <link href="http://git-scm.com/docs/gittutorial">Official git tutorial</link>
pt_BR: <link href="http://git-scm.com/docs/gittutorial">Tutorial oficial do git</link>

note: (itstool) path: item/p
en: <link href="https://try.github.io/">Interactive git tutorial</link>
pt_BR: <link href="https://try.github.io/">Tutorial interativo de git</link>

note: (itstool) path: item/p
en: <link href="http://www.git-tower.com/learn/">git-tower tutorial</link>
pt_BR: <link href="http://www.git-tower.com/learn/">Tutorial git-tower</link>

note: (itstool) path: info/desc
en: Versioning and releasing libraries and applications
pt_BR: Versionamento e lançamento de bibliotecas e aplicativos

note: (itstool) path: synopsis/p
en: Module versioning differs for libraries and applications: libraries need a libtool version specified in addition to their package version. Applications just have a package version.
pt_BR: O versionamento é diferente para módulos de bibliotecas e aplicativos: as bibliotecas precisam de uma versão de libtool especificada junto com a versão de seu pacote. Por sua vez, aplicativos só possuem uma versão de pacote.

note: (itstool) path: item/p
en: Libraries and applications have a package version of the form <em>major.minor.micro</em>. (<link xref="#package-versioning"/>)
pt_BR: Bibliotecas e aplicativos possuem uma versão de pacote na forma de <em>maior.menor.micro</em>. (<link xref="#package-versioning"/>)

note: (itstool) path: item/p
en: Libraries additionally have a libtool version of the form <em>current:revision:age</em>. (<link xref="#libtool-versioning"/>)
pt_BR: Adicionalmente, bibliotecas possuem uma versão de libtool na forma de <em>atual:revisão:idade</em>. (<link xref="#libtool-versioning"/>)

note: (itstool) path: item/p
en: Version numbers should be updated for each release (using release and post-release increments). (<link xref="#release-process"/>)
pt_BR: Os números de versão devem ser atualizados a cada lançamento (usando incrementos de lançamento e pós-lançamento). (<link xref="#release-process"/>)

note: (itstool) path: item/p
en: Package versions should be incremented for feature changes or additions. (<link xref="#package-versioning"/>)
pt_BR: As versões de pacotes devem ser incrementados por alterações ou adições de recursos. (<link xref="#package-versioning"/>)

note: (itstool) path: item/p
en: Libtool versions should be updated for API changes or additions. (<link xref="#libtool-versioning"/>)
pt_BR: As versões de libtool devem ser atualizadas por alterações ou adições de API. (<link xref="#libtool-versioning"/>)

note: (itstool) path: item/p
en: Even/odd <em>minor</em> package versions can be used respectively for stable/unstable releases. (<link xref="#stable-unstable-versions"/>)
pt_BR: Versões <em>menores</em> pares/ímpares de pacotes podem ser usadas respectivamente para lançamentos estáveis/instáveis. (<link xref="#stable-unstable-versions"/>)

note: (itstool) path: section/title
en: Package Versioning
pt_BR: Versionamento de pacote

note: (itstool) path: section/p
en: Both libraries and applications have a package version of the form <em>major.minor.micro</em>.
pt_BR: Bibliotecas e aplicativos possuem uma versão de pacote na forma de <em>maior.menor.micro</em>.

note: (itstool) path: section/p
en: The package version number is that passed to <code>AC_INIT()</code>, and the one which is typically known as the project’s version number. For example, the Debian package for a library will use the library’s package version (though may also include the major version number in the package name to allow for <link xref="parallel-installability">parallel installability</link>). Package versions are updated by the following rules:
pt_BR: O número de versão de pacote é aquele passado para <code>AC_INIT()</code> e que geralmente é conhecido como número de versão do projeto. Por exemplo, o pacote Debian para uma biblioteca vai usar a versão de pacote da biblioteca (apesar de também poder incluir o número de versão maior no nome de pacote para permitir <link xref="parallel-installability">instalabilidade paralela</link>). Versões de pacotes são atualizadas pelas seguintes regras:

note: (itstool) path: item/p
en: If breaking <link xref="api-stability">API compatibility</link> in a library, or making a large change to an application which affects everything (such as a UI redesign), increment major and set minor and micro to 0.
pt_BR: Se for quebrar a <link xref="api-stability">compatibilidade de API</link> em uma biblioteca, ou fazer uma alterações a um aplicativo que afeta tudo (tal como um redesenho da interface gráfica), incremente a versão maior e defina a menor e micro para 0.

note: (itstool) path: item/p
en: Otherwise, if changing or adding a feature, or adding any API, increment minor and set micro to 0.
pt_BR: Do contrário, se for alterar ou adicionar um recurso, ou adicionar qualquer API, incremente a versão menor e defina micro para 0.

note: (itstool) path: item/p
en: Otherwise (if making a release containing only bug fixes and translation updates), increment micro.
pt_BR: Do contrário (se for fazer um lançamento contendo apenas correções de erros e atualizações de tradução), incremente a versão micro.

note: (itstool) path: section/p
en: Note that the minor version number should be updated if any API is added.
pt_BR: Note que o número da versão menor deve ser atualizada se qualquer API for adicionada.

note: (itstool) path: section/title
en: Libtool Versioning
pt_BR: Versionamento de libtool

note: (itstool) path: section/p
en: Libraries have two version numbers: a libtool version which tracks ABI backwards compatibility (see <link xref="api-stability"/>), and a package version which tracks feature changes. These are normally incremented in synchronization, but should be kept separate because ABI backwards compatibility is not necessarily related to feature changes or bug fixes. Furthermore, the two version numbers have different semantics, and cannot be automatically generated from each other.
pt_BR: Bibliotecas possuem dois números de versão: uma versão de libtool que rastreia a compatibilidade reversa com ABI (veja <link xref="api-stability"/>) e uma versão de pacote que rastreia alterações de recursos. Esses são normalmente incrementados em sincronização, mas devem ser mantidos separados por causa de compatibilidade reversa com ABI não está necessariamente relacionada a alterações de recursos ou correções de erros. Além do mais, os dois números de versões possuem semânticas diferentes e não podem ser gerados automaticamente para cada um.

note: (itstool) path: section/p
en: A good overview of libtool versioning, and the differences from package versioning, is given in the <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link>; another is in the <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool manual</link>.
pt_BR: Uma boa visão geral do versionamento de libtool, e as diferenças para versionamento de pacote, é fornecida no <link href="https://autotools.io/libtool/version.html">Autotools MythBuster</link>; outro está no <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">manual do libtool</link>.

note: (itstool) path: section/p
en: To update the libtool version, follow the algorithm given in the comments below. This is a typical <file>configure.ac</file> snippet for setting up libtool versioning:
pt_BR: Para atualizar a versão do libtool, siga o algoritmo fornecido nos comentários abaixo. Esse é tipicamente um bloco de código do <file>configure.ac</file> para configurar versionamento de libtool:

note: (itstool) path: section/p
en: The following snippet can be used in a <file>Makefile.am</file> to pass that version info to libtool:
pt_BR: O bloco de código a seguir pode ser usado em um <file>Makefile.am</file> para passar aquela informação de versão para o libtool:

note: (itstool) path: section/code
en: my_library_la_LDFLAGS = -version-info $(LT_VERSION)
pt_BR: minha_biblioteca_la_LDFLAGS = -version-info $(LT_VERSION)

note: (itstool) path: section/title
en: Stable and Unstable Package Versions
pt_BR: Versões estáveis e instáveis de pacote

note: (itstool) path: section/p
en: Most GNOME modules follow a convention for stable and unstable releases. The minor version is even for stable releases and is odd for unstable releases. For example, the 3.20.* versions are stable, but the 3.19.* versions are unstable. The 3.19.* versions can be seen as alpha and beta releases of the 3.20 version.
pt_BR: A maioria dos módulos do GNOME seguem uma convenção para lançamentos estáveis e instáveis. A versão menor é par para lançamentos estáveis e é ímpar para lançamentos instáveis. Por exemplo, as versões 3.20.* são estáveis, mas as versões 3.19.* são instáveis. As versões 3.19.* podem ser vistas como lançamentos alfa e beta da versão 3.20.

note: (itstool) path: section/p
en: A new micro <em>stable</em> version (e.g. 3.20.0 → 3.20.1) doesn’t add new features, only translation updates and bug fixes. On the other hand, <em>unstable</em> micro releases (e.g. 3.19.1 → 3.19.2) can add API, or change or remove API which was added in a previous micro release in that minor series.
pt_BR: Uma nova versão micro <em>estável</em> (ex.: 3.20.0 → 3.20.1) não adiciona novos recursos, apenas atualizações de tradução e correções de erro. Por outro lado, lançamentos micro <em>instáveis</em> (ex.: 3.19.1 → 3.19.2) podem adicionar API, ou alterar ou remover API que foi adicionada em um lançamento micro anterior naquela séries menores.

note: (itstool) path: section/p
en: The libtool version should be updated only for stable package versions.
pt_BR: A versão libtool deve ser atualizada apenas para versões de pacote estável.

note: (itstool) path: section/title
en: Release Process
pt_BR: Processo de lançamento

note: (itstool) path: section/p
en: The standard process for making a release of a module increments the libtool version (if the module is a library) at the time of release, then increments the package version number immediately afterwards (this is called a post-release increment).
pt_BR: O processo padrão para fazer um lançamento de um módulo incrementa a versão de libtool (se o módulo é uma biblioteca) em tempo de lançamento e, imediatamente após, incrementa o número de versão do pacote (isso é chamado de “incremento pós-lançamento” ou, em inglês, “post-release increment”)

note: (itstool) path: section/p
en: Updating the libtool versions at the time of release means that they are only incremented once for all ABI changes in a release. The use of post-release increment for package versions means the package version number is not outdated (still equal to the previous release) during the development cycle.
pt_BR: Atualizar as versões de libtool em tempo de lançamento significa que eles são incrementados apenas uma vez para todas as alterações de ABI em um lançamento. O uso de incremento pós-lançamento para versões de pacotes significa que o número de versão de pacote não está desatualizado (ainda igual ao lançamento anterior) durante o ciclo de desenvolvimento.

note: (itstool) path: section/p
en: The release process (based on the <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME release process</link>):
pt_BR: O processo de lançamento (baseado no <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">processo de lançamento do GNOME</link>):

note: (itstool) path: item/p
en: Make sure code is up to date: <cmd>git pull</cmd>
pt_BR: Certifique-se de que o código esteja atualizado: <cmd>git pull</cmd>

note: (itstool) path: item/p
en: Make sure you have no local changes: <cmd>git status</cmd>
pt_BR: Certifique-se de que você tenha nenhuma alteração local: <cmd>git status</cmd>

note: (itstool) path: item/p
en: If the release is for a stable package version, increment the libtool version number in <file>configure.ac</file> (if it exists)
pt_BR: Se o lançamento é para uma versão de pacote estável, incremente o número de versão de libtool no <file>configure.ac</file> (se ele existir)

note: (itstool) path: item/p
en: Add an entry to the <file>NEWS</file> file
pt_BR: Adicione uma entrada ao arquivo <file>NEWS</file>

note: (itstool) path: item/p
en: Run <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> and ensure it succeeds
pt_BR: Execute <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> e certifique-se de que foi concluído com sucesso

note: (itstool) path: item/p
en: Fix any issues which come up, commit those changes, and restart at step 3
pt_BR: Corrija quaisquer problemas que aparecerem, faça o commit das alterações e reinicie no passo 3

note: (itstool) path: item/p
en: If <cmd>make distcheck</cmd> finishes with “[archive] is ready for distribution”, run <cmd>git commit -a -m "Release version x.y.z"</cmd> (where ‘x.y.z’ is the package version number)
pt_BR: Se <cmd>make distcheck</cmd> finalizar com “[archive] is ready for distribution”, execute <cmd>git commit -a -m "Release version x.y.z"</cmd> (sendo “x.y.z” o número da versão do pacote)

note: (itstool) path: item/p
en: Run <cmd>git push</cmd>
pt_BR: Execute <cmd>git push</cmd>

note: (itstool) path: item/p
en: If that fails due to other commits having been pushed in the meantime, run <cmd>git pull</cmd> to merge your commit on the branch followed by a second <cmd>git push</cmd>. This is an exception to the GNOME guideline to have a linear Git history (<link xref="version-control#use-of-git"/>). If you prefer to have a linear history, you need to restart at step 1.
pt_BR: Se isso falhar em razão de outros commits terem sido enviados (push) neste meio tempo, execute <cmd>git pull</cmd> para mesclar seu commit no ramo seguido por um segundo <cmd>git push</cmd>. Isso é uma exceção às diretrizes do GNOME de ter um histórico de git linear (<link xref="version-control#use-of-git"/>). Se você prefere ter um histórico linear, você precisa reiniciar o passo 1.

note: (itstool) path: item/p
en: Tag the release: <cmd>git tag -s x.y.z</cmd> (where ‘x.y.z’ is the package version number)
pt_BR: Crie uma tag de lançamento: <cmd>git tag -s x.y.z</cmd> (sendo “x.y.z” o número de versão do pacote)

note: (itstool) path: item/p
en: Run <cmd>git push origin x.y.z</cmd> (where ‘x.y.z’ is the package version number)
pt_BR: Execute <cmd>git push origin x.y.z</cmd> (sendo “x.y.z” o número de versão do pacote)

note: (itstool) path: section/p
en: The release is now complete, and the post-release version increment can be done:
pt_BR: O lançamento agora está completo e o incremento de versão pós-lançamento pode ser feita:

note: (itstool) path: item/p
en: Increment the package version number in <file>configure.ac</file>
pt_BR: Incremente o número de versão de pacote no <file>configure.ac</file>

note: (itstool) path: item/p
en: Run <cmd>git commit -a -m "Post-release version increment"</cmd>
pt_BR: Execute <cmd>git commit -a -m "Post-release version increment"</cmd>

note: (itstool) path: section/p
en: The package archive generated by <cmd>make distcheck</cmd> can now be uploaded to download.gnome.org or distributed in other ways.
pt_BR: O arquivo de pacote gerado por <cmd>make distcheck</cmd> agora pode ser enviado para download.gnome.org ou distribuído em outras formas.

note: (itstool) path: info/desc
en: Good, readable code keeps the project maintainable
pt_BR: Código bom e legível mantém o projeto manutenível

note: (itstool) path: page/title
en: The Importance of Writing Good Code
pt_BR: A importância de um código bem escrito

note: (itstool) path: page/p
en: GNOME is a very ambitious free software project, and it is composed of many software packages that are more or less independent of each other. A lot of the work in GNOME is done by volunteers: although there are many people working on GNOME full-time or part-time for here, volunteers still make up a large percentage of our contributors. Programmers may come and go at any time and they will be able to dedicate different amounts of time to the GNOME project. People’s “real world” responsibilities may change, and this will be reflected in the amount of time that they can devote to GNOME.
pt_BR: GNOME é um projeto de software livre muito ambicioso e é composto por muitos pacotes de software que são mais ou menos independentes entre si. Muito do trabalho no GNOME é feito por voluntários: apesar de haver muitas pessoas trabalhando no GNOME em tempo integral ou parcial, voluntários ainda fazem uma grande porcentagem de nossas contribuições. Programadores podem ir e vir todo o tempo e eles serão capazes de dedicar diferentes parcelas de tempo para o projeto do GNOME. As responsabilidades do “mundo real” das pessoas podem alterar e isso refletirá na quantidade de tempo que eles devotam ao GNOME.

note: (itstool) path: page/p
en: Software development takes long amounts of time and painstaking effort. This is why most part-time volunteers cannot start big projects by themselves; it is much easier and more rewarding to contribute to existing projects, as this yields results that are immediately visible and usable.
pt_BR: Desenvolvimento de software leva grandes quantidades de tempo e esforços penosos. É por isso que a maioria dos voluntários em tempo parcial não conseguem iniciar grandes projetos por si próprio; é muito mais fácil e recompensador contribuir para projetos existentes, pois isso traz resultados que são imediatamente visíveis e usáveis.

note: (itstool) path: page/p
en: Thus, we conclude that it is very important for existing projects to make it as easy as possible for people to contribute to them. One way of doing this is by making sure that programs are easy to read, understand, modify, and maintain.
pt_BR: Portanto, nós concluímos que é muito importante para os projetos existentes torná-los o mais simples possível para que pessoas contribuam para eles. Uma forma de fazer isso é se certificar de que programas são fáceis de ler, entender, modificar e manter.

note: (itstool) path: page/p
en: Messy code is hard to read, and people may lose interest if they cannot decipher what the code tries to do. Also, it is important that programmers be able to understand the code quickly so that they can start contributing with bug fixes and enhancements in a short amount of time. Source code is a form of <em>communication</em>, and it is more for people than for computers. Just as someone would not like to read a novel with spelling errors, bad grammar, and sloppy punctuation, programmers should strive to write good code that is easy to understand and modify by others.
pt_BR: Um código bagunçado é difícil de ler e as pessoas podem perder o interesse se elas não puderem decifrar o que o código tenta fazer. Ademais, é importante que os programadores sejam capazes de entender o código rapidamente de forma que eles possam começar a contribuir com correções de erro e aprimoramentos em uma pequena quantidade de tempo. Código-fonte é uma forma de <em>comunicação</em> e é mais para pessoas que para computadores. Assim como alguém não gostaria de ler uma novela com erros de escrita, gramática ruim e pontuação desleixada, programadores devem se esforçar para escrever um bom código que seja fácil de ser entendido e modificado por outros.

note: (itstool) path: page/p
en: The following are some important qualities of good code:
pt_BR: A seguir estão algumas qualidades importantes de um bom código:

note: (itstool) path: item/title
en: Cleanliness
pt_BR: Limpeza

note: (itstool) path: item/p
en: Clean code is easy to read with minimum effort. This lets people start to understand it easily. This includes the coding style itself (brace placement, indentation, variable names), and the actual control flow of the code.
pt_BR: Um código limpo é fácil de ler com esforço mínimo. Isso permite que pessoas comecem a entendê-lo facilmente. Isso inclui o estilo de codificação em si (colocação de chaves, recuo, nomes de variáveis) e o fluxo de controle do código.

note: (itstool) path: item/title
en: Consistency
pt_BR: Consistência

note: (itstool) path: item/p
en: Consistent code makes it easy for people to understand how a program works. When reading consistent code, one subconsciously forms a number of assumptions and expectations about how the code works, so it is easier and safer to make modifications to it. Code that <em>looks</em> the same in two places should <em>work</em> the same, too.
pt_BR: Um código consistente facilita o entendimento de como um programa funciona. Ao ler um código consistente, forma-se subconscientemente um número de presunções e expectativas sobre como o código funciona, então é mais fácil e seguro fazer modificações nele. Um código que <em>se parece</em> o mesmo em dois locais deve <em>funcionar</em> da mesma forma, também.

note: (itstool) path: item/title
en: Extensibility
pt_BR: Extensibilidade

note: (itstool) path: item/p
en: General-purpose code is easier to reuse and modify than very specific code with lots of hardcoded assumptions. When someone wants to add a new feature to a program, it will obviously be easier to do so if the code was designed to be extensible from the beginning. Code that was not written this way may lead people into having to implement ugly hacks to add features.
pt_BR: Um código com propósito geral é mais fácil de reusar e modificar do que um código muito específico com diversas presunções codificadas. Quando alguém deseja adicionar um novo recurso a um programa, obviamente será mais fácil fazer isso se o código foi projetado para ser extensível desde o começo. Um código que não foi escrito dessa forma pode levar pessoas a ter que implementar hacks feios e adicionar recursos.

note: (itstool) path: item/title
en: Correctness
pt_BR: Corretismo

note: (itstool) path: item/p
en: Finally, code that is designed to be correct lets people spend less time worrying about bugs, and more time enhancing the features of a program. Users also appreciate correct code, since nobody likes software that crashes. Code that is written for correctness and safety (i.e. code that explicitly tries to ensure that the program remains in a consistent state) prevents many kinds of silly bugs.
pt_BR: Finalmente, um código que é projetado para ser correto permite que as pessoas gastem menos tempo se preocupando com erros, e mais tempo melhorando os recursos de um programa. Usuários também apreciam um código correto, já que ninguém gosta de software que trava. Código que é escrito prezando pelo corretismo e segurança (i.e. código que explicitamente tenta se certificar de que o programa permaneça em um estado de consistência) evita muitos tipos de erros bobos.

note: (itstool) path: section/title
en: Book References
pt_BR: Referências literárias

note: (itstool) path: item/p
en: <link href="http://www.cc2e.com">Code Complete</link>, by Steve McConnell.
pt_BR: <link href="http://www.cc2e.com">Code Complete</link>, por Steve McConnell.

note: (itstool) path: item/p
en: <link href="http://martinfowler.com/books/refactoring.html"> Refactoring: Improving the Design of Existing Code </link>, by Martin Fowler.
pt_BR: <link href="http://martinfowler.com/books/refactoring.html"> Refactoring: Improving the Design of Existing Code </link>, por Martin Fowler.

note: (itstool) path: item/p
en: <link href="http://en.wikipedia.org/wiki/Design_Patterns"> Design Patterns: Elements of Reusable Object-Oriented Software </link>, by Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides.
pt_BR: <link href="http://en.wikipedia.org/wiki/Design_Patterns"> Design Patterns: Elements of Reusable Object-Oriented Software </link>, por Erich Gamma, Richard Helm, Ralph Johnson e John Vlissides.

note: (itstool) path: item/p
en: <link href="http://astore.amazon.com/gnomestore-20/detail/020163385X"> Object-Oriented Design Heuristics </link>, by Arthur Riel.
pt_BR: <link href="http://astore.amazon.com/gnomestore-20/detail/020163385X"> Object-Oriented Design Heuristics </link>, por Arthur Riel.
