Naming Methodology

[JimLewis]

Hi Patrick,
I see lots of code. However, I think we might want to agree on naming methodology as it would be nice if all were the same.

I would like something that is obvious - even to people who don't have the secret decoder ring for the naming convention. The conventions that use T_ or _T are a reflection of a generation of people who could not type.

Going further mode views are new. When people see V_ they are going to thing variable.

Best Regards,
Jim

[Paebbels]

The proposal is using

• Uses UpperCammelCase
• T_... for types
• V_... for views
• ..._Vector for arrays
• ..._In if the main data is flowing inwards
• ..._Out if the main data is flowing outwards
• Abbreviated letters are in full-uppercase
• PCB related interfaces are called ..._PCB, so types without this extension are fabric internal signals
  (the majority of types will be of this class)
• All records are declared with their matching array type.
• Aliases are defined, if a type has a second very popular name.

Unfortunately, VHDL is not very clever when it comes to names. Everything resides in a single scope, therefore we need to distinguish types from objects and views.

[JimLewis]

I propose that instead of

• T_ ... that we use _Interface or Interface for interface types
• T_... that we use something that is understood naturally without a secret decoder ring. I have used Type as a suffix, but am open.
• V_... that we use _View or View
• For ..._In also consider In as suffix (w/o _). "In" follows main data flow
  • Similar thoughts for ...Out
  • Like: I2C_InView vs I2CViewIn vs I2CView_In
  • No Like: I2CInView vs I2C_In_View vs I2C_View_In
• For each interface there shall be a vector of that interface also declared of the form: _Interface_Vector
• _PCB vs FPGA Internals
• View naming for AddressBus which historically was Master/Initiator and Slave/Target
  • AxiAddress should be unsigned.
  • _SlaveView is not going to fly in the US (and it will make my wife angry with me)
  • Master is probably ok since it is used in so many different contexts.

[Paebbels]

@JimLewis please review #12 and accept if you agree.

[LarsAsplund]

@Paebbels @JimLewis I think simplicity is important considering that there are many people that will have to adapt to a style they are not used to. Looking at the code we have identifiers like DifferentialLane_Interface, DifferentialLane_TransmitterView and DifferentialLane_Interface_Vector. Where to use camel case and where to use underscore becomes complex. Is there a significant value in that complexity? Why not just underscores or just camel case?

[JimLewis]

@LarsAsplund I understand your concern. Here the '_' provides visual separation of the name vs. the modifier(s). DifferentialLate is the base name. _Interface designates that it is an interface. _TransmitterView designates that it is a view for the transmitter. _Interface_Vector designates that it is an array of interfaces.

OTOH, if we were to write, Differential_Lane_Transmitter_View then one does not readily see the name DiferentialLane from the modifiers. One does not see that it is a single modifier TransmitterView vs multiple separate modifiers like _Interface_Vector.

Likewise the same could be said if we were to write it as, DifferentialLaneTransmitterView.

[JimLewis]

@Paebbels
Looks like all of the files have tabs in them. The tabs render in GitHub as 8 spaces.

Can we propose to not use tabs and have the editors convert tabs on entry to
spaces instead? This is particularly important when copying entities and
making them into components as suddenly the tab stops are not aligned
anymore. In addition to make a component instance, I like to copy the
component or entity and edit from there. It really helps with column
cuts to have only spaces as the alignment then never shifts.

[JimLewis]

I propose that for packages, we use some sort of naming that differentiates their names,

• Such as Axi4LitePkg or Axi4Lite_Pkg . I prefer it without the _ as that is what OSVVM does.

Can we alias design unit names - such as packages to have a new name?
This would help transition from an older naming style to a newer one.
If not, we need to add it as part of the language revision.

[LarsAsplund]

@JimLewis I understand the idea but is the value of being clear about the modifiers really worth the extra complexity? If there is a significance in terms of understanding what is meant it would mean that the identifier cannot be understood if you read it for me since they all sound alike. Doesn't that suggest that there is a problem with the fundamental naming?

I think the fact that you're suggesting that it should be _Interface but not _Pkg is a good example of the type of confusion complex rules leads to ;-)