AKA – Taming the wild west of RPGLE/SQLRPGLE source code comments with IBM i BOB, turning cryptic developer scribbles into a perfectly standardized, comment utopia.
If you spend any time maintaining IBM i systems like I do, you know how messy legacy RPGLE and SQLRPGLE source can get. One program after another with zero comments, or worse, random comments scattered everywhere that tell you nothing useful. It slows down onboarding, makes debugging a nightmare, and kills any hope of quick understanding when you open a file in in your IDE of choice.
That is exactly why I started enforcing a clean, standardized comment block at the top of every RPGLE and SQLRPGLE member in my repositories. And the fastest way to roll this out across hundreds of programs? IBM i BOB, the AI coding assistant that lives right inside your IDE.
BOB does not just slap on generic comments. You give it your rules once, and it applies them perfectly, every time, using the triple-slash documentation style that modern IBM i extensions love. This gives you hover tips, better outline views, and actual documentation integration inside the editor.
The exact standardized RPG comment format I used
Here is my target header layout: based on various best practice standards, with some little personal tweaks and some IBM BOB flair.
It is simple, consistent, and built for IBM i programmers:
///
/// 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
///Notice the three key elements:
- Triple-slash (///) lines so the IBM i VS Code extensions treat them as proper documentation.
- A clear, comprehensive program purpose description right at the top.
- A bulleted feature list that gives you the “what does this thing actually do?” view in seconds.
- Clear modification history
That is it. No more guessing. Every program in the repo now follows the same pattern.
How to let BOB do the heavy lifting
You do not have to edit files by hand. BOB handles the whole thing in seconds.
Step 1: Open your project in BOB
Fire up the Bob IDE (the full VS Code fork from IBM). Connect to your IBM i system or open the local clone of your Git repository that contains the source. Make sure you are in the folder that holds your QRPGLESRC or QSQLSRC libraries.
Step 2: Store your comment standards in a BOB Config file (BOB.JSON)
Open any RPGLE or SQLRPGLE member. Click the BOB chat panel and type a prompt like this:
“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: [paste the example block above]. Replace any existing comments at the top of the file.”
Step 3: Update a single file (perfect for testing)
Hit enter and watch BOB rewrite the header. It reads the entire program, figures out the real purpose, extracts the features, and inserts the new block. Approve the change and you are done.
Make any small changes until you get this one source file in the new comment block standard you like.
Once ready – let’s do it for the entire repository!
Something that would take us hours but takes BOB just minutes:
Step 4: Roll it out to the entire repository
For the real power move, use one prompt that scans everything. In the BOB chat window type:
“Scan the entire repository and update every RPGLE and SQLRPGLE source file. Add standardized triple-slash comments at the top of each member. Include a comprehensive Program Purpose description and a clear Features list. Use ‘-‘ as the separator character. Follow this exact format: [paste the example block]. Do not change any executable code, only the comment header.”
BOB will walk the folder structure, open each qualifying member, analyze the logic, generate the proper header, and propose the changes. You can review them one by one or let it apply everything in batch. It respects your .rules or AGENTS.md files too, so once you define the standard in your project config, future scans stay perfectly consistent.
Hint’n’tips from my IBM i BOB experiences
- Always give BOB the exact format block in your prompt. The clearer you are, the less it has to guess.
- If the program already has some comments, tell BOB to “replace the existing header only” so you keep any inline notes further down.
- For SQLRPGLE files, the same prompt works perfectly. BOB understands embedded SQL and factors it into the purpose and features.
- After the run, do a quick compile and test. The /// lines are pure comments, so they never affect runtime.
Why this matters on IBM i
Standardized triple-slash headers turn your source from black boxes into living documentation. New team members open a program and immediately see the purpose and features. IDE tools show hover documentation. Code reviews become faster. And when you hand the repo off to the next person, they actually understand what they are looking at.
BOB makes this trivial. What used to take days of manual editing now takes one well-crafted prompt.
Give it a try on your next IBM i project. Drop your first test file into BOB and watch the magic happen. Once you see how clean and consistent everything becomes, you will never go back to the old way.
Let me know in the comments how it works for you, or if you have a twist on the format that fits your shop even better. Happy coding on the IBM i!
