Naming conventions for FB in/out which are/shall become part of the 4diac standard library?

[MartinMelikMerkumians]

I have noticed that a lot PRs to add new FBs have been issued in the recent past.

Some of those FBs heavily deviate from the naming schemes we used in the past, which was based on the IEC 61131-3 standard FBs and functions.

I feel we should establish a common naming convention for FBs which are part of, or shall be added to, our standard library, as we are doing the the rest of our code. I think the reasons are clear, a common theme and knowing what to expect and what to avoid in naming ports. internal variables,, etc.

To give my personal opinion, we should avoid

• single letter identifiers for the public interface
• do not use Hungarian notation
• shall not differ in a single symbol (exceptions may apply here)

identifiers should always:

• stick to names as defined in the standard where applicable
• convey the meaning of the port/internal variable

What are your thoughts?

Cheers, Martin

[azoitl]

@MartinMelikMerkumians thanks for starting this discussion I think now that we are getting more and more FBs this is getting more and more important. I totally agree that hungarian notation is a no go.

Does anyone know some guidelines that we could use as starting point, e.g., PLC open?

[mx990]

I really like the idea of defining coding guidelines for IEC 61499 blocks. I also agree that we should not use Hungarian notation.

Does anyone know some guidelines that we could use as starting point, e.g., PLC open?

There are coding guidelines published by PLCopen¹, but a lot of them seem to be more meta guidelines that projects have to define themselves, such as You shall define the words to avoid in object names or Define the use of case. However, they may still serve as a good starting point for defining our own coding guidelines.

Footnotes

1. https://www.plcopen.org/download_file/force/ff60e817-eee5-442d-b718-a357a7279c7e/342/ ↩

[gravemalte]

I agree, apart from that I would also suggest that we start using tags to mark PRs. I find it quite hard to spot which part a PR is about. Tags like FB addition, FB change, FB IEC 61131-3, or whatever part of the IDE the PR is about (also open to better tag names). (I hope this also fits into this discussion, if not sorry for hijacking).

[azoitl]

This is form e a different discussion and should be kept separate from this one.

[diplfranzhoepfinger]

I started a similar Discussion some time ago, just cannot remember on which Channel.

one main Topic is e.g. Naming of indexed inputs.
we have quite some inconsistency there: some blocks use IN0, IN1, IN2, others use IN1, IN2, IN3.

[mx990]

The IEC 61131-3 standard states in section 6.6.1.4.1 that the default names should be IN1, IN2, and so on. If there is only one input, the name should be IN. I believe we should follow that convention, as well.

[diplfranzhoepfinger]

OK, F_SEL, E_SELECT, E_SWITCH, E_DEMUX (while E_DEMUX_2,4,8 already fixed) E_N_TABLE,
for me personally i like the 1-2 more, as it is more like the mechanical Engeneers count. so IEC 61131-3 choose it wisely in my Opinion.

[MartinMelikMerkumians]

Ok, seems that there are no further comments now. How to proceed?

I can try to sum the current consensus in a file. What would be the prefered format? Asciidoc?

[azoitl]

It would be great if you could sum up the current consensus.

We have in our documentation a specification section for whitepapers. I think this could also be something like an Eclipse 4diac whitepaper. If you agree then it should go there and be Asciidoc for easier maintenance.

I started a draft compliance profile for OPC UA for Configurabilty using OPC UA in Asciidoc in that section: eclipse-4diac/4diac-documentation@main...azoitl:4diac-documentation:opcuComplianceProfile

Maybe that can serve as reference. Please note that since I did that we changed the header of our documentation files to better integrated with our web-page. Therefore please have a look at another asciidoc for the yaml header that we need.