Todo Based Coding in ABAP

[keremkoseoglu]

Today, I would like to demonstrate a very simple but effective programming habit that I use in ABAP development: "TODO based coding".

The idea is to plant TODO comments into the code (typically among multiple programs / classes) before actually starting to write / modify code. That enables us a few things:

• Planning before coding


• Simplifying large refactoring tasks


• Figuring any semantic / functional gaps before modifying the code


• Eliminating the risk of forgetting things


• New programmers can take over incomplete programs

However, in order to make this technique effective, we need to make the compiler / IDE warn us if there are TODO's left in the compiled code. Otherwise, incomplete code might go to production.

Looking at some other platforms;

• Pycharm (Python IDE) shows #TODO comments as a separate list in the IDE


• XCode (Swift IDE) evaluates #warning commands as compiler warnings and shows them every time you compile the code

As far as I know, ABAP lacks such a feature. The closest thing that I know is the task list feature of Eclipse, but they are stored in the local machine; so a new programmer doesn't see them at all.

My simple but effective solution is to use a harmless fake pragma: ##TODO.

SAP doesn't recognize this pragma, so every time I check or activate a code containing ##TODO , SAP will show a warning. Eclipse or SE80, works in both.

Here is how a typical todo looks like:

##TODO.

" Complete ZCL_CLASS1=>METHOD1 first

" call METHOD1 here

" ensure that the returned value is OK

" otherwise, raise an exception

Me & some fellow ABAP programmers are using this technique since a while, and we are happy with the results.

This approach can also be used when the architect and programmer are different people. The architect can create all the programs, classes, critical methods, interfaces, etc and fill them with ##TODO comments. After that, programmers can step in and start coding; clearing the architectural ##TODO 's.

You can also get creative and invent your own fake pragmas; such as: ##TODO_TICKET_123 or ##TODO_PRIO_2 .

I hope that this approach will benefit other fellow developers as well.

[BaerbelWinkler]

Thanks for this sweet and simple approach to create inline to-do lists, Karem!

Cheers

Bärbel

[fabianlupa]

I use ##TODO too after having seen the idea some time ago in some SCN article.

Hopefully SAP will never create the TODO pragma because then the warnings will disappear.

We actually have a simple custom ATC check to find these and read an optional comment after the pragma (for example ##TODO. " Comment). Unfortunately dynamic elements (like the comment) only get shown as "..." in the ATC result list, so not quite the TODO-list other IDEs have in other languages.

[matthias_maisch]

Thank you! I really like it.

So far I used regular todo-comments and source scanner (rpr_abap_source_scan) to generate some kind of work list, but this approach in combination with ATC/SCI looks really good. I'll definitely give it a try.

[Peter_Inotai]

It's a cool idea, thanks for sharing it. Simple, but works perfectly.

[pokrakam]

I like the fake pragma idea, will definitely use that. In some projects we have custom ATC checks to scan for todo in comments, but at sites where ATC itself is still a vague todo / #onefineday this is a really quick and easy alternative.

However in many cases it can be more beneficial to write a unit test instead. There is the XP theory that one should write a unit test right before or after you write the functionality it tests. But if you have a design in your head right now, a unit test is a good way to document it. The bonus is you’re already part way there when you come back to it later. Just mark it as a tolerable failure so your tests still pass.

METHOD method1_result_is_valid. 

  data(val) = cut->method1( ).

  cl_abap_unit_assert=>not_initial( 

      act   = val 

      level = if_aunit_constants=>tolerable ).

ENDMETHOD.

When the work is eventually done, just remove the level parameter to turn it into a real error. If needed, add the relevant expected value or other tests.

[UweFetzer_se38]

Hi Fabian,

would be great if you would upload your ATC check to https://github.com/larshp/abapOpenChecks

 

[PaulBuettner]

Hey Guys,

nice idea to make it more TODO List like - atm we only have "ABAP Tokens" check in our system searching for TODO and co.

In Result list it's displayed with check message "Search String Number 0001 Found in: ..."

Way more easier to implement but not this nice.

BR,

Paul

[ennowulff]

I preferred another approach: I often use a class ZCL_TODO with some methods stating similar to yours:

• URGENT


• NICE_TO_HAVE


• PERFORMANCE


• QUESTION

The advantages to this approach are the following:

1: You can define parameters so that you can describe the todo task:

zcl_todo=>performance( what = 'check if join might be faster' who = 'John' ).

zcl_todo=>urgent( 'wrong field used! should be XXX' ).

2: If you run a cross-reference on the class or methods, you get a nice list with what to do. Yes, CI also does it but I find a cross reference more intuitive.

 

The disadvantage to pragmas: even if the class methods are empty, you have real code. Pragmas might be less "dangerous". Maybe using pragmas is better for use in eclipse.

[larshp]

https://docs.abapopenchecks.org/checks/70/ already does something similar, developed and contributed by https://github.com/pcf0

[Peter_Inotai]

I wonder if anybody using Eclipse tried tasks (https://mcuoneclipse.com/2016/05/24/to-do-lists-with-eclipse-tasks-view/) for the same purpose? I think it could be also an option, but I never tried it.

 

[Florian]

I use the approach Lars mentioned above and pretty happy with it.

Just placing Keywords into comments and find these again with my own checks. So I'm absolutely clean and can add markers for Code review, refactoring and whatever I want to.

The idea of Peter I also have in my mind, but didn't find time to dig deeper to get it up and running as it doesn't is there for ABAP 🙂

[ŁukaszPęgiel]

The idea of Peter is a good idea of next plugin for ADT or function inside it 🙂

[raghug]

I have used Eclipse tasks, and they work pretty nicely. The one advantage over the Pragma is that the list continues to be in front of you even if you have closed the source page in Eclipse. The disadvantage is that unless you set up a server, the list is only yours and can't be shared by other developers.

[Peter_Inotai]

Thanks for sharing your experience.

[bbalci]

Nice idea, this is something I always needed.

[pokrakam]

After seeing code that uses these, I've decided I really don't like ##TODO pragmas.

The problem is when working in Eclipse: The editor shows you errors, warning and other interesting things next to the scrollbar.
But ##TODO are shown as warnings so you end up with lots of fake warning markers littering the scrollbar, making it more difficult to spot "real" warnings. 

[joachimrees1]

Wow, this sounds interesting! I might try it! Thanks florian.henninger for pointing me to it!

[Florian]

You know... there is always something to learn out there 🙂

Every single day.

[michael_gutfleisch]

Todo or not todo that's the question 😉

About 15 years ago I've developed my own todo-browser for ABAP. Having that in place it turned out that I eagerly added todo comments in my code. In the beginning it made me happy to see my growing list of todos. But that happyness did not last forever. It turned out that it is difficult to share todos with other developers. It is not that simple to write a short todo comment which can be understood by other colleagues. And sometimes colleagues also did not agree that a certain todo should be done... the your clean code is not my clean code syndrome.

At some point in time I realized that it is much more beneficial in fixing issues right away instead of spending hours and hours in managing todos.

And if the issue is more complex maybe a backlog item is the better choice.