Reading through the LRM, and it appears to imply anything can be aliased, but when I try the following, ActiveHDL tells me a design unit is expected:
entity some_entity is
.....
end entity;
alias another_name is some_entity;
The LRM states (in 6.6.1) that
An object alias is an alias whose alias designator denotes an object (i.e., a constant, a variable, a signal, or a
file). A nonobject alias is an alias whose alias designator denotes some named entity other than an object.
An alias can be declared for all named entities except for labels, loop parameters, and generate parameters.
Or is it just the case that because an alias is a declarative item, it must exist in an declarative region? But given that an alias takes on the same class as the aliased item, surely it should be allowed in the same region? This appears to compile ok:
package alias_package is
alias another_name is work.some_entity;
end package;
Explanation for the above request: Lets say I want to rename some_entity, but it is used all over my design. Creating an alias to it would allow this, keeping the old name as an alias to the new one. Using the package would be unsuitable here as it would still require name modification at instantiation.
Is this worthy of a request for the next LRM?
Or is it just the case that because an alias is a declarative item, it must exist in an declarative region?
Yes. A design file is comprised of one or more design units and an entity declaration is a design unit. A design unit is comprised of one or more nested declarative regions. The root declarative region (with an optional context clause encompasses the design unit itself and any subordinate secondary design units.
There's no delimiter for declarative regions other than the end of a design unit.
But given that an alias takes on the same class as the aliased item, surely it should be allowed in the same region?
No. A declaration doesn't take effect (it's name doesn't become visible) until after the declaration is complete. Here, after end [entity_simple_name] ;.
A new design unit begins with optional context items (beginning with reserved words library, use or context) followed by a primary unit declaration or secondary unit body (indicated by one of the reserved words entity, architecture, package, configuration, context (here ignoring PSL, tool directives and comments).
Design units are independently analyzed.
The classes of aliases are object and non-object. An alias declaration targets the declaration of a named entity (and some name declarations are implicit).
Is this worthy of a request for the next LRM?
This question is a request for a subjective opinion without a clear use case (providing examples, particularly in a design hierarchy). The reason isn't clear. What work are you trying to avoid?
As an opinion otherwise, no.
There are also parts of the standard that are poorly supported by synthesis vendors that already address modifying binding from the default by exception (configuration declarations containing context specifications or component instantiation with the reserved word configuration).
Related
This question already has an answer here:
What is Hungarian Notation? [duplicate]
(1 answer)
Closed 8 months ago.
I have recently started working in a system that includes the data type in the fieldnames for every record. I'm writing up the documentation for this system (in particular the coding conventions), and as a history lesson, I wanted to include a reference to this style of naming convention.
In the past, I know it was very standard to use names like
dim strName
dim intAge
dim fltIncome
To help keep track of datatypes in dynamically typed languages (VBS in the case above). I also, know that this convention was actually named after somebody who wrote a lengthy description about why this is a good idea.
Does anyone know the name of this convention, or have good references they could share?
COM doesn't use Hungarian Notation at all. The Windows API does. And its useful enough. I've bolded the pat below that refutes Hungarian Notation in COM.
This is from https://learn.microsoft.com/ms-my/previous-versions/windows/desktop/automat/naming-conventions
Choose names for exposed objects, properties, and methods that can be
easily understood by users of the application. The guidelines in this
section apply to all of the following exposed items:
Objects — implemented as classes in an application.
Properties and methods — implemented as members of a class.
Named arguments — implemented as named parameters in a member function.
Constants and enumerations — implemented as settings for properties and methods.
Use Entire Words or Syllables
It is easier for users to remember complete words than to remember
whether you abbreviated Window as Wind, Wn, or Wnd.
When you need to abbreviate because an identifier would be too long,
try to use complete initial syllables. For example, use AltExpEval
instead of AlternateExpressionEvaluation.
Use Don't use
Application App
Window Wnd
Use Mixed Case
All identifiers should use mixed case, rather than underscores, to
separate words.
Use Don't use
ShortcutMenus Shortcut_Menus, Shortcutmenus, SHORTCUTMENUS, SHORTCUT_MENUS
BasedOn basedOn
Use the Same Word Used in the Interface
Use consistent terminology. Do not use names like HWND that are
based on Hungarian notation. Try to use the same word users would
use to describe a concept.
Use Don't use
Name Lbl
Use the Correct Plural for the Class Name
Collection classes should use the correct plural for the class name.
For example, if you have a class named Axis, store the collection of
Axis objects in an Axes class. Similarly, a collection of Vertex
objects should be stored in a Vertices class. In cases where English
uses the same word for the plural, append the word "Collection."
Use Don't use
Axes Axiss
SeriesCollection CollectionSeries
Windows ColWindow
I will clarify the question a bit. I have read (almost completely) the Go specification, FAQ, Effective Go, and, of course, Tour of Go.
I know that Go is a "pass by value" language and even managed to reason about this behavior and understand all the implications.
All assignments in Go also create copies. In some cases, it's just a value, in some -- a pointer. For some data structures, it's a bit trickier in that the whole structure is copied and might include an implicit pointer to another data structure.
The question is: what in the language specification says explicitly that assignments always create copies?
I feel like it doesn't even need to be mentioned once you understand that there are no references in Go, but the section on assignment statements in the specification doesn't even mention the pass-by-value semantics.
I feel like there must be something in the documentation that describes the behavior in detail, and I, due to lack of some foundational misunderstanding, fail to realize the explanation is there.
What in the language specification says explicitly that assignment always creates copies?
Nothing explicit, but you can maybe deduce this from Variables, which nicely addresses also the case of function signatures:
A variable declaration or, for function parameters and results, the signature of a function declaration or function literal reserves storage for a named variable.
If storage is reserved, when later you assign the result of a unary expression to it — e.g. another variable —, then it must be a copy, otherwise you would have memory aliasing. Which is what Dave Cheney is talking about in There is no pass-by-reference in Go.
Unlike C++, each variable defined in a Go program occupies a unique memory location.
This also has one more important implication, which is the zero value. If you don't provide an expression to initialize a variable in its declaration, the storage reserved for it is given the zero value as default value.
Without going into too much detail, these excerpts from the spec should provide some clarity:
A variable is a storage location for holding a value.
A variable's value [...] is the most recent value assigned to the variable.
At the language level, defining "copying" of values isn't really necessitated. The important implication of copying as we commonly understand it, is that modifying the "copied to" value will not alter the "copied from" value *. This property can be inferred from the above quotations.
(important to note here that "value" and "data structure" are not the same thing. A data structure may be comprised of multiple values.)
The spec actually explicitly talks about this here:
https://golang.org/ref/spec#Calls
In particular:
After they are evaluated, the parameters of the call are passed by value to the function and the called function begins execution. The return parameters of the function are passed by value back to the caller when the function returns.
About assignments: All assignments in most of the languages I know of create copies of values (see Python exception in the comments). A copy of the value on the RHS is assigned to the LHS. If the RHS is a pointer, then a copy of that pointer is assigned to the LHS.
When I compile my project in Quartus (15.0 Webedition) I get following error message:
10430 VHDL Primary Unit Declaration error at nios.vhd: primary unit "NIOS" already exists in library "nios"
In my project files I have the file "NIOS.vhd". After compiling, Quartus generates another file in the db-folder with the name "nios.vhd". This files is not the same as my file "NIOS.vhd" and therefore I get this error message. What is not clear at this point, why Quartus generates another file in the database? How can I get rid of this problem?
See QuartusII Help -
VHDL Primary Unit Declaration error at <location>: primary unit "<name>" already exists in library "<name>" (ID: 10430)
CAUSE: In a primary unit declaration at the specified location in a VHDL Design File (.vhd), you declared the specified primary unit. However, the specified library already contains a primary unit with the same name.
See IEEE Std 1076-2008
13.1 Design units, para 2:
primary_unit ::= entity_declaration
| configuration_declaration
| package_declaration
| package_instantiation_declaration
| context_declaration
| PSL_Verification_Unit
para 5:
The name of a primary unit is given by the first identifier after the initial reserved word of that unit. Of the secondary units, only architecture bodies are named; the name of an architecture body is given by the identifier following the reserved word architecture. Each primary unit in a given library shall have a simple name that is unique within the given library, and each architecture body associated with a given entity declaration shall have a simple name that is unique within the set of names of the architecture bodies associated with that entity declaration.
1.3 Structure and terminology of this standard, 1.3.1 General, para 4:
In this document, the word shall is used to indicate a mandatory requirement. The word should is used to indicate a recommendation. The word may is used to indicate a permissible action. The word can is used for statements of possibility and capability.
1.3.3 Semantic description, para 2:
The following terms are used in these semantic descriptions with the following meanings:
erroneous: The condition described represents an ill-formed description; however, implementations are not required to detect and report this condition. Conditions are deemed erroneous only when it is impossible in general to detect the condition during the processing of the language.
error: The condition described represents an ill-formed description; implementations are required to detect the condition and report an error to the user of the tool.
The 'shall have' is mandatory in VHDL, where a violation is an ill-formed description and is reported as an error.
It's complaining your declaration of nios doesn't match an existing declaration already in the library. (If they matched the existing declaration would be replaced):
13.1 Design units, para 1:
Certain constructs are independently analyzed and inserted into a design library; these constructs are called design units. One or more design units in sequence comprise a design file.
13.5 Order of analysis, para 5:
A given library unit is potentially affected by a change in any library unit whose name is referenced within the given library unit. A secondary unit is potentially affected by a change in its corresponding primary unit. If a library unit is changed (e.g., by reanalysis of the corresponding design unit), then all library units that are potentially affected by such a change become obsolete and shall be reanalyzed before they can be used again.
So if re-analyzed a primary unit of the same entity class (13.1, primary_unit) you'd replace the primary unit. Try with a different entity class of primary unit and you'll get an error.
Back to QuartusII Help:
ACTION: Compile the two primary units into different libraries or assign them unique names.
You state your working directory contains your analyzed design files and a file named nios.vhd that's a distinct name from your design file NIOS.vhd.
The issue isn't file name, it's primary unit name. In this case it's a primary unit name Altera feels free to use indiscriminately in the process of synthesis. Thankfully it's a primary unit of a different entity class. You'd be left with circular analysis dependencies (from 13.5) that'd be harder to fathom.
You should change your primary unit name, and because it's common to tie primary unit name to file name (while a design file can contain any number of design units), you might also change your design file name.
There is a more generic question asked here. Consider this as an extension to that.
I understand that classes represent type of objects and we should use nouns as their names. But there are function objects supported in many language that acts more like functions than objects. Should I name those classes also as nouns, or verbs are ok in that case. doSomething(), semantically, makes more sense than Something().
Update / Conclusion
The two top voted answers I got on this shares a mixed opinion:
Attila
In the case of functors, however, they represent "action", so naming them with a verb (or some sort of noun-verb combination) is more appropriate -- just like you would name a function based on what it is doing.
Rook
The instance of a functor on the other hand is effectively a function, and would perhaps be better named accordingly. Following Jim's suggestion above, SomethingDoer doSomething; doSomething();
Both of them, after going through some code, seems to be the common practice. In GNU implementation of stl I found classes like negate, plus, minus (bits/stl_function.h) etc. And variate_generator, mersenne_twister (tr1/random.h). Similarly in boost I found classes like base_visitor, predecessor_recorder (graph/visitors.hpp) as well as inverse, inplace_erase (icl/functors.hpp)
Objects (and thus classes) usually represent "things", therefore you want to name them with nouns. In the case of functors, however, they represent "action", so naming them with a verb (or some sort of noun-verb combination) is more appropriate -- just like you would name a function based on what it is doing.
In general, you would want to name things (objects, functions, etc.) after their purpose, that is, what they represent in the program/the world.
You can think of functors as functions (thus "action") with state. Since the clean way of achieving this (having a state associated with your "action") is to create an object that stores the state, you get an object, which is really an "action" (a fancy function).
Note that the above applies to languages where you can make a pure functor, that is, an object where the invocation is the same as for a regular function (e.g. C++). In languages where this is not supported (that is, you have to have a method other than operator() called, like command.do()), you would want to name the command-like class/object a noun and name the method called a verb.
The type of the functor is a class, which you may as well name in your usual style (for instance, a noun) because it doesn't really do anything on its own. The instance of a functor on the other hand is effectively a function, and would perhaps be better named accordingly. Following Jim's suggestion above, SomethingDoer doSomething; doSomething();
A quick peek at my own code shows I've managed to avoid this issue entirely by using words which are both nouns and verbs... Filter and Show for example. Might be tricky to apply that naming scheme in all circumstances, however!
I suggest you give them a suffix like Function, Callback, Action, Command, etc. so that you will have classes called SortFunction, SearchAction, ExecuteCommand instead of Sort, Search, Execute which sound more like names of actual functions.
I think there are two ways to see this:
1) The class which could be named sensibly so that it can be invoked as a functor directly upon construction:
Doer()(); // constructed and invoked in one shot, compiler could optimize
2) The instance in cases where we want the functor to be invoked multiple times on a stateless functor object, or perhaps for stylistic reasons when #1's syntax is not preferable.
Doer _do;
_do(); // operator () invocation after construction
I like #Rook's suggestion above of naming the class with words that have the same verb and noun forms such as Search or Filter.
I guess that most factory-like methods start with create. But why are they called "create"? Why not "make", "produce", "build", "generate" or something else? Is it only a matter of taste? A convention? Or is there a special meaning in "create"?
createURI(...)
makeURI(...)
produceURI(...)
buildURI(...)
generateURI(...)
Which one would you choose in general and why?
Some random thoughts:
'Create' fits the feature better than most other words. The next best word I can think of off the top of my head is 'Construct'. In the past, 'Alloc' (allocate) might have been used in similar situations, reflecting the greater emphasis on blocks of data than objects in languages like C.
'Create' is a short, simple word that has a clear intuitive meaning. In most cases people probably just pick it as the first, most obvious word that comes to mind when they wish to create something. It's a common naming convention, and "object creation" is a common way of describing the process of... creating objects.
'Construct' is close, but it is usually used to describe a specific stage in the process of creating an object (allocate/new, construct, initialise...)
'Build' and 'Make' are common terms for processes relating to compiling code, so have different connotations to programmers, implying a process that comprises many steps and possibly a lot of disk activity. However, the idea of a Factory "building" something is a sensible idea - especially in cases where a complex data-structure is built, or many separate pieces of information are combined in some way.
'Generate' to me implies a calculation which is used to produce a value from an input, such as generating a hash code or a random number.
'Produce', 'Generate', 'Construct' are longer to type/read than 'Create'. Historically programmers have favoured short names to reduce typing/reading.
Joshua Bloch in "Effective Java" suggests the following naming conventions
valueOf — Returns an instance that has, loosely speaking, the same value
as its parameters. Such static factories are effectively
type-conversion methods.
of — A concise alternative to valueOf, popularized by EnumSet (Item 32).
getInstance — Returns an instance that is described by the parameters
but cannot be said to have the same value. In the case of a singleton,
getInstance takes no parameters and returns the sole instance.
newInstance — Like getInstance, except that newInstance guarantees that
each instance returned is distinct from all others.
getType — Like getInstance, but used when the factory method is in a
different class. Type indicates the type of object returned by the
factory method.
newType — Like newInstance, but used when the factory method is in a
different class. Type indicates the type of object returned by the
factory method.
Wanted to add a couple of points I don't see in other answers.
Although traditionally 'Factory' means 'creates objects', I like to think of it more broadly as 'returns me an object that behaves as I expect'. I shouldn't always have to know whether it's a brand new object, in fact I might not care. So in suitable cases you might avoid a 'Create...' name, even if that's how you're implementing it right now.
Guava is a good repository of factory naming ideas. It is popularising a nice DSL style. examples:
Lists.newArrayListWithCapacity(100);
ImmutableList.of("Hello", "World");
"Create" and "make" are short, reasonably evocative, and not tied to other patterns in naming that I can think of. I've also seen both quite frequently and suspect they may be "de facto standards". I'd choose one and use it consistently at least within a project. (Looking at my own current project, I seem to use "make". I hope I'm consistent...)
Avoid "build" because it fits better with the Builder pattern and avoid "produce" because it evokes Producer/Consumer.
To really continue the metaphor of the "Factory" name for the pattern, I'd be tempted by "manufacture", but that's too long a word.
I think it stems from “to create an object”. However, in English, the word “create” is associated with the notion “to cause to come into being, as something unique that would not naturally evolve or that is not made by ordinary processes,” and “to evolve from one's own thought or imagination, as a work of art or an invention.” So it seems as “create” is not the proper word to use. “Make,” on the other hand, means “to bring into existence by shaping or changing material, combining parts, etc.” For example, you don’t create a dress, you make a dress (object). So, in my opinion, “make” by meaning “to produce; cause to exist or happen; bring about” is a far better word for factory methods.
Partly convention, partly semantics.
Factory methods (signalled by the traditional create) should invoke appropriate constructors. If I saw buildURI, I would assume that it involved some computation, or assembly from parts (and I would not think there was a factory involved). The first thing that I thought when I saw generateURI is making something random, like a new personalized download link. They are not all the same, different words evoke different meanings; but most of them are not conventionalised.
I'd call it UriFactory.Create()
Where,
UriFactory is the name of the class type which is provides method(s) that create Uri instances.
and Create() method is overloaded for as many as variations you have in your specs.
public static class UriFactory
{
//Default Creator
public static UriType Create()
{
}
//An overload for Create()
public static UriType Create(someArgs)
{
}
}
I like new. To me
var foo = newFoo();
reads better than
var foo = createFoo();
Translated to english we have foo is a new foo or foo is create foo. While I'm not a grammer expert I'm pretty sure the latter is grammatically incorrect.
I'd point out that I've seen all of the verbs but produce in use in some library or other, so I wouldn't call create being an universal convention.
Now, create does sound better to me, evokes the precise meaning of the action.
So yes, it is a matter of (literary) taste.
Personally I like instantiate and instantiateWith, but that's just because of my Unity and Objective C experiences. Naming conventions inside the Unity engine seem to revolve around the word instantiate to create an instance via a factory method, and Objective C seems to like with to indicate what the parameter/s are. This only really works well if the method is in the class that is going to be instantiated though (and in languages that allow constructor overloading, this isn't so much of a 'thing').
Just plain old Objective C's initWith is also a good'un!