This question already has an answer here:
- “Comments are a code smell” [closed] 34 answers
As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats or explanations could be added in-line while more complex constructions would be referred to by name and version number to allow a quick lookup in the documentation.
The two main reason they might not understand the syntax are because it's a new addition to the language or it's syntax that is rarely used by "average" developers. Assume that using this syntax is the recommended approach and not about me wanting to write fancy code. (No, I'm not XOR swapping in high-level languages.)
On the one hand, comments are there to facilitate maintenance and if I provide that explanation I could save a future developer a lot of effort and reading. On the other hand, I could argue that syntax documentation is readily available and that any decent developer could be expected to keep up to date on new developments or, failing that, shouldn't have any trouble figuring it out using the tools (IDE help) and documentaiton available to him.
For context, this question was prompted by recent updates to SAP's ABAP syntax which adds new grouping and filtering mechanics to loops and a number of other statements. Many legacy developers and client-side maintenance teams won't be familiar with this syntax for years (if ever).
For this question, assume that commenting your code is a good practice.
As csw comments, one option is to simply not use this new syntax until the maintainers have caught up, but as I hinted, some of those maintainers simply won't ever catch up. In my industry maintenance of the code is often handed over to small in-house developers once the project is delivered and they can be notorious for being stuck in "legacy mode". Writing functionally obsolete code as a crutch for out-of-touch programmers just doesn't seem like a good or defensible practice.
In my particular situation, the ABAP syntax updates offer some dramatic performance and readability improvements. They introduce a number of common modern operations to the ancient ABAP language like casting operators. The
GROUP BY I linked is another good example that replaces complex, illegible and bug-prone code with a simple alternative. For a concrete syntax example, I can replace
READ TABLE itab WITH ... TRANSPORTING NO FIELDS. IF sy-subrc = 0. ... ENDIF.
IF line_exists( itab[ ... ] ). ... ENDIF.
For those interested, this PDF covers many of the new features. Slide 29 and 30 offer two good example of how drastic the difference can be.
Regarding the suggested duplicate, there are some useful answers there but my question covers a more specific case. You could probably summarise my question as "Should I ignore the
document *why* rather than *how* paradigm when when doing so might greatly simplify maintenance for inexperienced developers?".