Inhalte

Comments

Table of Contents

Common

comments should be used rarely because comments tend to become outdated over time!

Comments are allowed for:

  • legal notices are not only allowed, but are required for headers for programs, GVLs, functions, classes, methods, and properties. The legal notices have a predefined format which can be found under Legal notices format

  • informative comments like an explanation of a data format or a design intent.

  • api documentation in Extended reStructuredText. For libraries, the api documentation is not only allowed, it’s required. For details check: https://ekvip.atlassian.net/wiki/spaces/CNMS/pages/1651376129.

Legal notices format

copy template legal notice

The specified form must be strictly adhered to. Only the current year must be entered in the copyright. The two tags with the colons are to be entered also in such a way, so that we are able to replace this via script with a license change.

(*

.. <legal notes>

legal notes
===========
| SPDX-FileCopyrightText: © 2024 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_

.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0

.. </legal notes>

*)

Comment examples

example for a simple stupid cycle time average calculator and I describe my design intent. 
METHOD calculateAndGetNewCycletimeAverageInMs :DINT
VAR_INPUT
  actCycleTimeInMs :DINT;
END_VAR
VAR_INST
  cycletimeAverageInMs  :DINT;
END_VAR
VAR CONSTANT
  ROUND_TO_INTEGER              :INT   := 0;
  QUANTIFIER_AVARAGE_CYCLETIME  :LREAL := 0.85;
  QUANTIFIER_NEW_CYCLETIME      :LREAL := 0.15;
  AVERAGE_IS_NOT_INITIALIEZED   :DINT  := 0;
END_VAR

cycletimeAverageInMs := SEL(
	(cycletimeAverageInMs = AVERAGE_IS_NOT_INITIALIEZED),
	cycletimeAverageInMs,
	actCycleTimeInMs
);

(* 
To safe memory we do not calculate the real cycle time average, but this is exact enough to show it on hmi. 
I don't want to waste memory for an information which the customer can get very exactly from mes.
Sometimes is plc cycle time a rare commodity
*) 
cycletimeAverageInMs := TO_DINT(
  F_RoundLREAL_EX(
    lrIn := ((TO_LREAL(cycletimeAverageInMs) * QUANTIFIER_AVARAGE_CYCLETIME) + (TO_LREAL(actCycleTimeInMs) * QUANTIFIER_NEW_CYCLETIME)),
    iPrecision := ROUND_TO_INTEGER
  )
);

calculateAndGetNewCycletimeAverageInMs := cycletimeAverageInMs;
example of a data format description as a comment
(*
CellSerialNumber is an alias type of STRING with a fixed length
 
format of the serial number is: 
[A](\d{6})([A-Z]\d{3})(\d{6})(\d{8})(\d{4})([0-1][0-9])([0-3][0-9])([0-2][0-9])(([0-5][0-9]){2})(\d{3})

[A](\d{6})
internal master data id starts always with the charachter A followed by 6 didgits there are now three types of cells 30mAh = A237873, 50mAh = A237875 and 100mAh = A237770 

([A-Z]\d{3})
supplier id is four characters long starts e.g. L237 is LG

(\d{6})
batch number

(\d{8})
current number

(\d{4})([0-1][0-9])([0-3][0-9])([0-2][0-9])(([0-5][0-9]){2})(\d{3})
timestamp YYYYMMDDhhmmssms

for example the string 'A237875L2376543210000000120210607133742123' means:
A237875 is 50mAh cell
L237 manufacturer is LG 
654321 batch number of the cell
00000001 this is first cell of the batch
20210607133742123 the cell was produced at 06/07/2021 13:37:42 123ms
*)
serialNumberOfCell:     CellSerialNumber;