Go Style: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(43 intermediate revisions by the same user not shown)
Line 12: Line 12:
The [[Go_Language_Modularization#Standard_library|Go standard library]] is a good source of code examples, comments and style.
The [[Go_Language_Modularization#Standard_library|Go standard library]] is a good source of code examples, comments and style.
=Line Length=
=Line Length=
Go has no line length limit. However, if the line feels too long, wrap it and indent it with an extra tab.
Go has no line length limit. However, if the line feels too long, wrap it and indent it with an extra tab.
=Comments=
{{Internal|Go_Language#Comments|Go Language | Comments}}


=<span id='Identifiers'></span>Naming=
=<span id='Identifiers'></span>Naming=
{{External|https://google.github.io/styleguide/go/guide#mixedcaps}}
{{External|https://google.github.io/styleguide/go/guide#mixedcaps}}


Naming is one of the most important aspects of Go development. Writing idiomatic Go requires understanding of its core naming principles.
Naming is one of the most important aspects of Go development. Writing idiomatic Go requires understanding of its core naming principles. The following rules apply to [[Go_Constants#Overview|constant]] and [[Go_Variables#Overview|variable]] [[Go_Language#Identifiers_(Names)|identifiers]], function names, type names, like struct or interface names.
 
Names have a semantic effect. The visibility of a name outside a package is determined whether its first character is upper case. See: {{Internal|Go_Language#Exported_Identifiers|Exported Identifiers}}


[[Go_Language#Identifiers_.28Names.29|Identifiers]] should use camel case: <code>SomeColor</code> or <code>someColor</code>, depending on whether they are visible outside the package or not. This is how [[Go_Packages#Packages_as_Encapsulation_Mechanism|package encapsulation]] works.
Go style recommends camel-case (mixed-case) for identifiers, rather than snake-case (underscore) to write multi-word names. Use <code>SomeVariable</code> or <code>someVariable</code>, depending on whether the variable is visible outside the package or not. Do not use snake case <code>some_variable</code>. Every exported name should be [[Go_Language#Comments|documented with a comment]].


Do not use snake case <code>some_color</code>.  
Names, and in special variable names, should be short rather than long. Long names do not automatically make things more readable. A helpful doc comment can often be more valuable than an extra long name.


Every exported name should be documented with a comment, following [[Go_Language#Comments|idiomatic comment conventions]].
Acronyms should have a consistent case. <code>URL</code> or <code>url</code> is correct, <code>Url</code> is not. Prefer all-capital acronyms, if it makes sense (<code>URL</code>).


Acronyms should have a consistent case. <code>URL</code> or <code>url</code> is correct, <code>Url</code> is not.
Use name abbreviations only if they are widely used (example: <code>fmt</code>). Avoid name collisions, when possible. If you introduce a set of string functions, avoid calling the package <code>strings</code> because a package with the same name exists in the standard library already.


When a variable, struct or interface is imported from another package, its name includes the package name or alias: <code>mypackage.MyVar</code>. This is a reason to [[Go_Packages#Try_to_Make_Package_Names_and_Exported_Names_Work_Together|try to make the package name and the feature name work together]].
When a feature is imported from another package, its name includes the package name or alias: <code>mypackage.MyVar</code>. This is a reason to [[Go_Packages#Try_to_Make_Package_Names_and_Exported_Names_Work_Together|try to make the package name and the feature name work together]].


Use name abbreviations only if they are widely used (example: <code>fmt</code>).
The greater the distance between a name's declaration and its uses, the longer the name should be.


Avoid name collisions, when possible. If you introduce a set of string functions, avoid calling the package <code>strings</code> because a package with the same name exists in the standard library already.
Where more specific rules apply to a particular kind of name, those rules are documented in a dedicated style section:


Other naming conventions:
==Constants==
* [[Go_Language#Source_File_Name_Conventions|Source Files Naming Conventions]]
{{Internal|Go_Constants#Naming|Constants Naming}}
* [[Go_Packages#Idiomatic_Package_Conventions|Idiomatic Package Conventions]]
==Variables==
* [[Go_Language#Idiomatic_Variable_Naming_Conventions|Idiomatic Variable Naming Conventions]]
{{Internal|Go_Variables#Naming|Variables Naming}}
* [[Go_Functions#Idiomatic_Function_Naming_Conventions|Idiomatic Function Naming Conventions]]
==Packages==
* [[Go_Structs#Idiomatic_Struct_Naming_Conventions|Idiomatic Struct Naming Conventions]]
{{Internal|Go_Packages#Package_Name|Package Names}}
* [[Go_Interfaces#Idiomatic_Interface_Conventions|Idiomatic Interface Conventions]]
==Interfaces==
* [[Go_Language_Error_Handling#Idiom|Idiomatic Error Conventions]]
{{Internal|Go_Interfaces#Idiomatic_Interface_Conventions|Interfaces}}
<font color=darkkhaki>Integrate this:
==Source Files==
* https://go.dev/talks/2014/names.slide#1
{{Internal|Go_Language#Source_File_Name_Conventions|Source File Naming}}
* https://golang.org/doc/effective_go.html#names
==Functions==
* https://blog.golang.org/package-names
{{Internal|Go_Functions#Naming|Function Naming}}
* https://rakyll.org/style-packages/
===Receivers===
</font>
{{Internal|Go_Language_Object_Oriented_Programming#Receiver_Naming|Receiver Naming}}
===Methods===
{{Internal|Go_Language_Object_Oriented_Programming#Method_Naming|Method Naming}}


=Comments=
===Getters and Setters===
{{Internal|Go_Language#Comments|Go Language &#124; Comments}}
=Idiomatic Error Handling=
{{Internal|Go_Language_Error_Handling#Idiomatic_Error_Handling|Idiomatic Error Handling}}
=Getters and Setters=
{{External|https://go.dev/doc/effective_go#Getters}}
{{External|https://go.dev/doc/effective_go#Getters}}


It is neither idiomatic, not necessary to put "Get" in the getter's name. If you have a field called owner (lower case, unexported), the getter method should be called <code>Owner()</code> (upper case, exported), '''not''' <code>Owner()</code>.
Go does not provide automatic support for getters and setters, but there is nothing wrong with programming getters and setters yourself.  


A setter function, if needed, should be called <code>SetOwner()</code>.
These are the conventions around naming the getters and setters, documented in [https://go.dev/doc/effective_go#Getters effective_go]:
 
* The field should be [[Go_Packages#Unexported_Members|unexported]] (lower-case name). Example: <code>name</code>.
* The getter method should have the same name as the field, except the for the first character, which is upper-case, making it exported. Example: <code>Name()</code>. It is neither idiomatic, not necessary to put "Get" in the getter's name. The method '''should not''' be called <code>GetName()</code>.
* The setter method should be called <code>SetOwner()</code>.
 
<syntaxhighlight lang='go'>
type SomeStruct struct {
name string // unexported
}
 
// Name is the getter method, exported. Must not be called GetName()
func (s *SomeStruct) Name() string {
return s.name
}
 
// SetName is the setter method, exported
func (s *SomeStruct) SetName(name string) {
s.name = name
}
</syntaxhighlight>
 
=Idiomatic Error Handling=
{{Internal|Go_Language_Error_Handling#Idiomatic_Error_Handling|Idiomatic Error Handling}}

Latest revision as of 23:52, 5 July 2024

External

Internal

Overview

The Go standard library is a good source of code examples, comments and style.

Line Length

Go has no line length limit. However, if the line feels too long, wrap it and indent it with an extra tab.

Comments

Go Language | Comments

Naming

https://google.github.io/styleguide/go/guide#mixedcaps

Naming is one of the most important aspects of Go development. Writing idiomatic Go requires understanding of its core naming principles. The following rules apply to constant and variable identifiers, function names, type names, like struct or interface names.

Names have a semantic effect. The visibility of a name outside a package is determined whether its first character is upper case. See:

Exported Identifiers

Go style recommends camel-case (mixed-case) for identifiers, rather than snake-case (underscore) to write multi-word names. Use SomeVariable or someVariable, depending on whether the variable is visible outside the package or not. Do not use snake case some_variable. Every exported name should be documented with a comment.

Names, and in special variable names, should be short rather than long. Long names do not automatically make things more readable. A helpful doc comment can often be more valuable than an extra long name.

Acronyms should have a consistent case. URL or url is correct, Url is not. Prefer all-capital acronyms, if it makes sense (URL).

Use name abbreviations only if they are widely used (example: fmt). Avoid name collisions, when possible. If you introduce a set of string functions, avoid calling the package strings because a package with the same name exists in the standard library already.

When a feature is imported from another package, its name includes the package name or alias: mypackage.MyVar. This is a reason to try to make the package name and the feature name work together.

The greater the distance between a name's declaration and its uses, the longer the name should be.

Where more specific rules apply to a particular kind of name, those rules are documented in a dedicated style section:

Constants

Constants Naming

Variables

Variables Naming

Packages

Package Names

Interfaces

Interfaces

Source Files

Source File Naming

Functions

Function Naming

Receivers

Receiver Naming

Methods

Method Naming

Getters and Setters

https://go.dev/doc/effective_go#Getters

Go does not provide automatic support for getters and setters, but there is nothing wrong with programming getters and setters yourself.

These are the conventions around naming the getters and setters, documented in effective_go:

  • The field should be unexported (lower-case name). Example: name.
  • The getter method should have the same name as the field, except the for the first character, which is upper-case, making it exported. Example: Name(). It is neither idiomatic, not necessary to put "Get" in the getter's name. The method should not be called GetName().
  • The setter method should be called SetOwner().
type SomeStruct struct {
	name string // unexported
}

// Name is the getter method, exported. Must not be called GetName()
func (s *SomeStruct) Name() string {
	return s.name
}

// SetName is the setter method, exported
func (s *SomeStruct) SetName(name string) {
	s.name = name
}

Idiomatic Error Handling

Idiomatic Error Handling