Naming

Here are the emergent-specific naming conventions -- please use these to keep the code as readable and consistent as possible!

First, we follow all the general Go conventions:

• https://golang.org/doc/effective_go.html#names
• https://github.com/golang/go/wiki/CodeReviewComments

And here are some additions for the GoKi framework:

• https://github.com/goki/ki/wiki/Naming

The three most important from the GoKi page are:

Formal names vs. Nicknames

There are generally two "views" of a given structural entity like a Layer:

• A Go interface that describes a set of methods, and is the way to create a virtual function calling pattern in Go, so that we can efficiently have more specialized versions of a given overall algorithm. emer defines overall structural interfaces for emer.Network and emer.Layer that allow e.g., the netview.NetView to be applied to any kind of network.

• The specific struct type that implements the interface, e.g., leabra.Layer.

The naming problem arises in the clash between the field names for the struct vs. the accessor methods onto those fields. e.g., you can't have both Name() in the interface and a field named .Name in the struct.

The solution we've adopted is to use "nicknames" for the struct (e.g., Nm), and "formal" names for the interface methods. The initial draft of emer did not follow this but this was corrected in 5/2019..

Accessors

We generally provide 2 methods for accessing elements in cases that might fail (e.g., by name):

• ThingByName(name string) *thing
• ThingByNameTry(name string) (*thing, error)

The first one should be used if you know the thing should exist -- in which case you can convert the return value (which is often an abstract interface type) directly into the type you know it should be. That is much more efficient. The second one should be used if it is acceptable for the thing not to exist -- you can then print out or popup a dialog for the error value.

Changes from C++ emergent

This is the principle from the Ki naming page:

• avoid adding generic terms like Item, Data, State, Run, Compute, etc to names -- you'll find that they are usually superfluous -- almost everything a computer does involves these things, so just focus on what uniquely applies to the particular case you're trying to name.

In C++ emergent, we used "Data" and "Compute" extensively, and have now removed all uses thereof, to the great benefit of making the code much more succinct and clear. The first version of the ra25.go example project still violated this principle, but has now been fixed..

Standard receiver names

For methods, the Go standard is to use a consistent, short abbreviation of the type for the receiver variable. We typically use 2 letters to make it easier to search-and-replace vs. a single letter.

To make code more portable for copy-paste programming, the following standard names are always used instead of renaming for each type:

• ly for all Layer methods, even if it is a specific kind of layer (e.g., GPiThalLayer)
• pj for all Prjns
• ev for for all env.Env environments

Leabra-specific naming issues

See the Leabra README for specific naming conventions for that algorithm.