Using BOB to standardize RPGLE/SQLRPGLE source code comments

Source Code Commenting Standards are one of the simplest ways to improve code readability, team collaboration, and long‑term maintainability on IBM i. In this lesson, you’ll learn how to use IBM BOB to automatically standardize comments across your RPGLE and SQLRPGLE source members; saving time, reducing inconsistency, and enforcing best practices across your development workflow.

Why Standardized Comments Matter

Clear, consistent comments help developers:

• Understand business logic quickly
• Reduce onboarding time for new team members
• Improve code reviews and audits
• Maintain legacy applications with confidence
• Avoid “tribal knowledge” pitfalls

On IBM i systems, where applications often live for decades, comment quality is not optional. It’s essential.

What BOB Brings to the Table

BOB is a modern build tool for IBM i that integrates beautifully with VS Code and other modern IDEs. When configured correctly, BOB can:

• Apply standardized comment templates

• Enforce formatting rules

• Insert or update module headers

• Normalize inline comments

• Ensure consistent metadata (author, date, purpose, parameters, etc.)

This transforms comment maintenance from a manual chore into an automated, repeatable process.

How BOB Standardizes RPGLE/SQLRPGLE Comments

Here’s the typical workflow:

1. Define Your Comment Templates

Create a reusable template for:

• Module headers
• Procedure headers
• Parameter descriptions
• Modification history
• Inline comment style

These templates become the “source of truth” for your team.

2. Configure BOB Rules

BOB’s configuration folder (.bob) allows you to specify:

• Which source files to scan
• Which templates to apply
• How to handle missing or outdated comments
• Whether to auto‑insert or auto‑correct comment blocks

3. Run BOB Against Your Source

BOB analyzes each RPGLE/SQLRPGLE member and:

• Inserts missing headers
• Updates outdated metadata
• Normalizes formatting
• Ensures consistent indentation and spacing

4. Review & Commit

Developers review the standardized output, commit the changes, and enjoy a cleaner, more maintainable codebase.

Example: Before & After

Here’s a conceptual example of what BOB can do:

Before

After

Cleaner. Clearer. Consistent.

Best Practices for Comment Standardization

To get the most from BOB:

• Keep templates short, clear, and useful

• Avoid duplicating information already obvious from code

• Document why, not just what

• Review templates quarterly to keep them relevant

• Train your team to rely on BOB instead of manual formatting

Standardizing comments in RPGLE and SQLRPGLE source members using IBM i BOB is a powerful way to modernize your development workflow. By automating comment formatting with reusable templates and consistent rules, BOB helps teams produce cleaner, more readable code that’s easier to maintain and audit. This not only improves the quality of your source members but also streamlines collaboration across developers working on legacy and modern IBM i applications.

How do we tell BOB how to standardize?

I came up with a standard code head block that I want to reflect to every RPGLE and SQLRPGLE in my repository:

This is the instruction I used for my github public repository :

"Update the header comments in this RPGLE source to use triple-slash documentation style. Add a comprehensive Program Purpose description based on the code logic. Include a clear Features list with bullet points. Use '-' as the separator character exactly as shown in this format:
///
/// Program: [PROGRAM_NAME] - [Brief Title]
///
/// Description: [Detailed description of what the program does, its purpose,
/// and how it fits into the larger system. Use multiple lines
/// for clarity and readability.]
///
/// Purpose: Educational/Production example demonstrating:
/// - [Key concept or feature 1]
/// - [Key concept or feature 2]
/// - [Key concept or feature 3]
/// - [Additional concepts as needed]
///
/// Features:
/// - [Feature 1 with brief explanation]
/// - [Feature 2 with brief explanation]
/// - [Feature 3 with brief explanation]
/// - [Additional features as needed]
///
/// Usage: [How to call/use the program]
/// [Example: CALL PROGRAM PARM('value')]
///
/// Parameters: (if applicable)
/// - param1: [Type] - [Description]
/// - param2: [Type] - [Description]
///
/// Dependencies: (if applicable)
/// - [File/table/service program dependencies]
/// - [External resources required]
///
/// Control Options: (if notable)
/// - [option]: [Explanation of why this option is used]
///
/// Modification History:
/// [Version] [Date] | [Author] | [Description of changes]
/// 2026-04-02 | Bob AI | Added comprehensive documentation
///
Replace any existing comments at the top of the file."

Come with me and let's do this in real time:

That was easy!

In Summary

With BOB’s repeatable configuration and template-driven approach, teams benefit from faster onboarding, reduced manual formatting, and a more professional development environment. Comment blocks become consistent across modules, procedures, and parameters, making business logic easier to understand and modify. Whether you're documenting new code or retrofitting legacy programs, BOB transforms comment maintenance from a tedious task into a reliable, automated process.

How about we store this as a TEMPLATE and make it repeatable?

Let's do exactly that in our next lesson....