TIA Portal Comment Standards: S7-1200/1500 Style Guide

1. Overview: Why Comment Standards Matter in TIA Portal Projects

PLC code without comments is a maintenance liability. In TIA Portal V18, V19, and V20 projects targeting S7-1200 and S7-1500 controllers, comments live in five distinct locations: tag tables, data blocks (DB), function blocks (FB), functions (FC), organization blocks (OB), and individual network titles plus network comments. Each location uses a different comment field, and each is exported or consumed differently by HMI, OPC UA, the web server, and TIA Portal Openness scripts.

When a supplier delivers uncommented code, the cost is borne during commissioning, FAT, and the next 15-20 years of plant operation. The original programmer often leaves the project after SAT, leaving the end user to reverse-engineer every rung. Mandating comment standards during the RFQ stage is dramatically cheaper than retrofitting comments during a shutdown.

Siemens publishes an official style guide that defines naming rules, comment locations, and required fields. The document is the primary reference any specification should cite, and it supersedes informal internal guidelines. This article consolidates that style guide, the multilingual comment workflows exposed by TIA Portal Openness, and field-proven checklist items for accepting or rejecting supplier code.

2. Official Reference: Siemens Programming Styleguide for S7-1200/1500

The canonical document is the Siemens "Programming Styleguide for S7-1200/1500" (entry ID 81318674 in the Siemens Industry Online Support knowledge base). The styleguide is delivered as a PDF and applies to all S7-1200/S7-1500 firmware versions supported by TIA Portal V16 and later.

Key sections of the styleguide that affect commenting:

• Naming conventions: identifiers use English, no special characters beyond underscore, prefix rules for tags (i_, q_, m_, t_ for input, output, marker, timer prefix patterns).
• Block header comments: every FB, FC, OB, DB requires a structured header containing block title, family, author, version, and purpose.
• Tag comments: each PLC tag, DB element, and I/O symbol carries a comment field of up to 254 characters that is exported to the web server and to HMI text lists.
• Network comments: every network title is mandatory; every network comment is recommended for logic with branch decisions or non-obvious behavior.
• SCL/FBD/LAD consistency: comments travel with the block when the block is copied, exported via Openness, or reused in libraries.

3. Block-Level Comments: OB, FB, FC, DB Header Structure

Every block in the program blocks folder carries four metadata fields exposed in the inspector window under Properties > Information:

Recommended header comment template for an FB:

// =====================================================================
// FB1021  Motor_M201_VFD_Control
// Family: Conveyor Drive
// Author: J.Smith  v1.4  2024-03-12
// Purpose: Speed reference, ramp, and fault handling for VFD-driven
//          conveyor motor M201. Interlocks with upstream E-Stop FB1050
//          and downstream jam detection FB1037.
// Safety: SIL1; no direct safety function; e-stop handled by F-CPU
// =====================================================================

The same template applies to OBs. For OB1 (main cycle), OB100 (warm restart), and OB101 (hot restart), comments must explicitly state the boot behavior and any non-default initialization.

4. Network Titles and Network Comments

Each network in FBD/LAD has two fields: Network title (single-line, ~64 chars in display) and Network comment (multi-line, 254 chars per line). SCL networks expose only a single comment line above the statement block, but the block header carries the equivalent of network title plus comment.

Field-proven rule: any network that contains a comparator (>, <, =), a math instruction (CALCULATE), or a timer (TON, TP) requires a comment that states the threshold value, the engineering unit, and the action triggered when the threshold is crossed.

5. PLC Tag and DB Element Comments

Comments on PLC tags propagate to four downstream consumers: the web server of the S7-1500 (S7-1500 FW V2.5+), HMI text lists in WinCC, OPC UA address space on the S7-1500 OPC UA server, and exported XML when using TIA Portal Openness.

Sample tag entries:

Tag: i_StartPB        Comment: Start pushbutton, NO contact, P&ID 201-PSH-014, PNP 24V
Tag: i_M201_SpeedFB   Comment: Speed feedback from VFD M201, 0-10V = 0-1500 rpm, AI4
Tag: q_M201_RunCmd    Comment: Run command to VFD M201; TRUE = run, FALSE = stop (freewheel)
Tag: t_DebounceRun    Comment: Run command debounce, preset 500 ms, prevents contact bounce

6. SCL Source Code Comment Conventions

SCL comments live in three distinct positions, each with different export behavior:

1. Block header (comment above the first line of code) - travels with the block.
2. Statement comments (// ... at end of line) - travel with the line; lost on round-trip if Openness export/import is misused.
3. Region markers (REGION ... END_REGION) - collapsible in the editor, exported as block-level metadata.

Recommended SCL skeleton:

// FB2010  Tank_Level_Control
// Family: Process
// Author: M.Chen  v2.1  2024-05-04
// Purpose: PID control for tank T-101 level via proportional valve.
//          Uses FB100 (CTRL_PID) and scales 4-20 mA to 0-100%.
REGION Inputs
  // i_LevelPV : 4-20 mA from LT-101, scaled 0-100%
  // i_LevelSP : setpoint from HMI, range 0-100%
END_REGION

REGION Logic
  // PI controller; Kp = 1.2, Ti = 30 s, derivative off
  // Output saturates at 0-100% to prevent valve over-travel
END_REGION

Inline statement comments should be reserved for lines where the formula or threshold is non-obvious; bulk commentary belongs in the block header or region comment.

7. Multilingual Comments via TIA Portal Openness

S7-1200/S7-1500 comment fields are multilingual-capable. TIA Portal stores each comment as a list of MultilingualText entries keyed by language. Languages supported in TIA Portal V20 include English (en-US, en-GB), German (de-DE), French (fr-FR), Spanish (es-ES), Italian (it-IT), Chinese (zh-CN), and Japanese (ja-JP). Each language is independently editable and independently exportable.

The official Siemens documentation for Openness comment export/import lives in the TIA Portal Openness API reference for V20. See the Export/Import multilingual comments in SCL page for the exact API surface and behavior.

Summary of behavior from the official TIA Portal Openness documentation:

• During SCL export via the Openness API, all configured language variants of a comment are exported to the XDB/AML file. To preserve all languages, the export must not be limited to a single culture.
• During SCL import, comments can be assigned per language. If the import target culture is omitted, the default project language is used.
• The C# API class is Siemens.Engineering.SW.Blocks.PlcBlock, with GetMultilingualText() and SetMultilingualText() methods on the comment field.

Minimal Openness C# snippet (TIA Portal V20) to read and write multilingual block comments:

// Read every language variant of a block's comment
PlcBlock fb = project.FindType<PlcBlock>().FirstOrDefault(b => b.Name == "FB1021");
MultilingualText mlText = fb.Comment.GetMultilingualText();
foreach (var entry in mlText)
{
    Console.WriteLine($"{entry.Language.CultureName}: {entry.Text}");
}

// Write German translation
var de = new CultureInfo("de-DE");
fb.Comment.SetMultilingualText(de, "VFD-geregelter Antrieb Foerderband M201");

8. Writing Comment Standards into Project Specifications

A specification clause that holds up in a contractual dispute must be specific. The following clause template can be inserted into a PLC software specification or supplier quality plan.

Sample specification text:

"The supplier shall provide complete, multilingual comments for all PLC software deliverables. Each organization block (OB), function block (FB), function (FC), and data block (DB) shall carry a Title, Comment, Family, and Author field as defined in the Siemens Programming Styleguide for S7-1200/1500 (Siemens Support entry ID 81318674). Each PLC tag and DB element shall carry a comment describing engineering unit, scaling, valid range, and P&ID reference where applicable. Every network in LAD/FBD shall carry a network title; every SCL block shall carry a header comment with author and version. Comment fields shall be populated for at least the project default language and English (en-US). Empty or placeholder comments shall be cause for rejection."

Supplementary checks that strengthen the specification:

• Reject code where Family fields are blank across the entire program blocks container.
• Reject code where DB element comments contain only the symbolic name restated.
• Reject code where ladder networks contain branches without comments.
• Require a comment audit report (CSV export of all blocks with empty comment fields) as a FAT deliverable.

9. Audit and Verification Procedure

The following procedure produces a measurable, repeatable comment-quality check in under 30 minutes for a typical mid-size project (5,000-15,000 tags).

1. Open the TIA Portal project and compile to ensure no errors.
2. Right-click the PLC device > Export to TIA Portal Openness-compatible XML. Use Openness to enumerate all blocks and tags.
3. For each block, read the four header fields (Title, Comment, Family, Author). Log any empty value.
4. For each tag table and DB, read the Comment property. Log any empty value or any value shorter than 10 characters.
5. For SCL blocks, parse the source // lines at the top of each block. Log any block with zero header comment lines.
6. Produce a CSV report: BlockName, BlockType, Title, CommentLength, Family, Author, MissingFields.
7. Accept the deliverable only if zero missing-field rows exist, or if the supplier commits in writing to remediate before SAT.

PowerShell + Openness is the most common script stack. Sample skeleton:

$tia = New-Object -ComObject TIA.TiaPortal
$process = $tia.GetProcesses() | Where-Object IsPrimary -eq $true
$project = $process.Project
$device = $project.Devices[0]
$blocks = $device.Blocks
$report = foreach ($b in $blocks) {
    [PSCustomObject]@{
        Name          = $b.Name
        Type          = $b.Type
        Title         = $b.Comment.Title
        CommentLength = $b.Comment.Comment.Length
        Family        = $b.Comment.Family
        Author        = $b.Comment.Author
    }
}
$report | Export-Csv -Path "C:\audit\comment_audit.csv" -NoTypeInformation

10. Common Pitfalls and Troubleshooting

11. Library and Type Reuse: Comments Must Travel

When a block is promoted to a global library (master copy + types), the comments travel with the type definition. However, instance DBs created from an FB type inherit only the comment of the static section; instance-specific comments must be added at the instance.

Best practice for libraries:

• Use a single Master copies folder per discipline (Motion, Safety, Process, Utilities).
• Apply a uniform Family string per folder so block pickers in the editor group logically.
• Document the library header comment convention in the library README.
• Never ship a master copy with empty comments; the instance will inherit the empty header.

12. Quick Checklist for Acceptance

• [ ] Every OB, FB, FC, DB has Title, Comment, Family, Author populated.
• [ ] Every PLC tag in default tag table has a comment ≥ 10 characters.
• [ ] Every DB element has a comment with engineering unit or state meaning.
• [ ] Every network in LAD/FBD has a title; non-trivial logic has a comment.
• [ ] Every SCL block has a header comment with author and version.
• [ ] At least one language variant is English (en-US or en-GB).
• [ ] Comment audit CSV is delivered with no empty fields.
• [ ] Openness export/import test preserves all language variants per the multilingual comments documentation.