This documentation is open to be edited by all CODESYS Forge developers. It can be used to share global information, which is of interest for developers of differnt projects.
The contents is not meant as dogmatic and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community. The developer adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!
As seen, this versioning scheme leaves "room" for (arbitrarily) smaller or larger code updates while also providing a clear overview of the development progress.
Of course, other versioning scheme's are possible (provide examples).
A versioning scheme I have used successfully for machines is this:
I will start in the middle as that is the most important, the state.
y = 0 = concept (just messing around with an idea)
y = 1 = development (goal in mind)
y = 2 = released for internal testing (devoloper thinks they are finished and are ready to run through internal testing)
y = 3 = released for stakeholder testing (testing complete, ready for testing with eg. Customer or product owner)
y = 4 = released for site (this version has all the testing and is ready for site)
y = 5 = installed on site (this version is installed on site, but is either not working or hasn't been tested)
y = 6 = commissioned (installed on site and somebody (customer?) is satisfied that it is working)
Now let's look to the least significant, version z. The first time you enter a new state you are on z=0. Any commits in that state, and z=z+1; Easy right?
Now the most significant, version x. The rule is "you cannot go backwards in y without incrementing x."
So that is the rules all covered. Now to some nuances or "what about when...".
Say you are in V0.3.0 (first stakeholder testing version) and the customer says "I want red to mean on". You do not need to go back to development stage or internal testing. You can simply make the change and commit as "V0.3.1 red now means on", then continue testing.
But what if next they said "you completely forgot the intake section of the machine specification!" Perhaps they threw the acceptance test sheets into the air and stormed out of the room. You can probably understand the state (y) may need to go back to development. So, your next commit is V1.1.0.
OK, so fast forward to commissioning. It is day 3 of commissioning and you are on V1.5.14. The customer is happy. You now make a commit (with no code changes from V1.5.14) to V1.6.0. The commit message might say something like "customer happy with site test" or even "developer happy the software is working" if that's how you run things.
A couple months later the customer asks "can you add an OFF delay to input 3?" You come round, do the change online, customer tests it and says it is fine. Just use V1.6.1 for your next commit.
A further 3 months and another small change is asked for. "We would like a trend of input 6." You go in on a down day, make the software change, but there's no product so you can't really test it. Commit the change as V2.5.0 (y=5, increase x by 1, reset z to zero). Two days later you check in with the customer. "All is good". Now you get a new commit, V2.6.0.
It is possible to skip steps as well. e.g. If it's decided a Factory Acceptance Test (y=3) isn't needed, go straight to 4.
when using RTS_IEC_HANDLE and RTS_IEC_RESULT types, please add SysTypes2 Interfaces (188.8.131.52);
if possible, use standard error codes (CmpErrors or CmpErrors2 Interfaces);
if possible, avoid using dynamic memory (the usage of NEW operator);
always use Structured Text (ST) language whenever possible as ST is by far the most versatile language, in which all operations, manipulations and functions are possible;
document the source code, add meaningful comments to it;
for modern coding style advice: read the CODESYS v3 library development tips as provided in CODESYS help,
The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point.
For further reading see e.g. Steve McConnell "Code Complete";
If you want to experiment with markdown syntax, create a project on your profile called "internaltest" and take away permissions of everyone but you.