Most ABAP developers know it is usually easier and faster to find something in ABAP programs than searching the documentation. There are two “buts” to this approach. Firstly, the job of reading ABAP code is easier if all descriptions are properly maintained. SAP mostly enforces you to fill in short description of every function module or method you write, but does it really explain what your code does? And second of all, simple ABAP code mostly misses the context: why does it do what it does? Appropriate comments, mostly at the beginning of function modules, methods and forms are necessary.
Writing comments and descriptions is a prerequisite to a good coding - an advice, you can find in any programming textbook. However, many programmers do not write comments, or their comments are technical only, and do not explain business reasons for some decisions.
And that’s where the ABAP Doc comes in. This documentation tool pulls information both from ABAP Dictionary and code comments. The result is interface description of a method or function module, along with comments. If the in-code documentation is written properly, you receive method interface along with description of what each method does. This is amended by code comments that should answer the most important questions: what this piece of code does and why does it do it that way.
If the generated documentation makes sense, in-code documentation is sufficient. In most cases it will not be good enough on the first try and it will need some more work. This additional work is done in-code, not in the document. This way, if you generate document again, years from now, it will contain information that is good enough.
Senior developer or team lead can review documentation generated from code produced by other developers. If it is readable without seeing code itself it should be readable in the future. It is important that this documentation addresses business issues: why we are writing this. It is easy enough to find out that this function module reads data from certain table but in the future we will need information why it is done and what business wanted.
The most important part is that the documentation is kept in code, and can be accessed by any developer directly in ABAP Workbench. And it can be printed anytime without searching folders on all disks that were intended ultimate documentation storage over the years.
https://github.com/kctdata/abapDoc
