I was wondering what people thought of proposing adding what is essentially a documentation feature to Ada. I thought it might be worthwhile to propose a means to document automatically inherited subprograms in a package spec. One of weaknesses to using inheritance is that you lose a lot of readability due to the subprogram specifications being in a potentially variety of different files that you have to glean to just to see what a type “can do”.
Currently the only way I have found to do this is to manually override each and every one and just call the base class version inside the new overridden one, but this is somewhat annoying sometimes as it opens up one to making logical mistakes (like type casting to the wrong ancestor, or parameter mix-up if they are the same subtype) just to essentially “document” what a type can do.
Additionally if the descendant type is really simple and doesn’t even need a package body normally, doing this means you need to now add a package body for the procedure bodies.
Maybe there is a better way that already exists (tips welcome here)? I was hoping to find a way that didn’t require a completion body if possible.
If not, I was thinking of maybe asking on the ARG github for some solutions / insights. Some (mostly not fleshed out) thoughts of ways to do this (that would need to be added):
procedure Do_Something(Self : Child_Type) with Inherited;
procedure Do_Something(Self : Child_Type) is overriding;
procedure Do_Something(Self : Child_Type) is new Parent_Package.Do_Something;
procedure Do_Something(Self : Child_Type) with Import, Convention => Intrinsic
And to think people already considers too verbose ! By god, please, no… If it doesn’t add information for the compiler or facilitate writing for the human, adding more demands would be terrible. This is the job of external tools, which already exist. If it’s just a matter of collecting ADT properties from all around your source code, automated documentation should be much very easy with our languages, being so semantically richer than others.
Or did I misunderstand ?
You’re opposed to people having options? This is not adding more demands. It’s asking about adding options for those who want them. It’s about adding readability options (again not requirements).
So you’d writing things just for cosmetics, to inform future readers (including yourself), with no effect on the program ? From reading the minutes and issues, working to the making of the language looks like a world of pain, I can’t imagine them agreeing. It seems like you’re describing Doxygen:
It automates the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in formats like HTML and PDF…
Nothing to do with or at all like Doxygen. This has nothing to do with comments at all. It could be a misunderstanding of what I was asking. I’m not the greatest word smith.
This is a violation of the S/W-engineering principle of locality, that everything you need to know about something should be in a single place. All uses of programming by type extension (except contrived examples designed to disprove this statement) violate this principle. Since S/W engineers don’t violate S/W-engineering principles, we can conclude that no one who engages in programming by type extension is a S/W engineer.
Such a better way exists; it is called programming by composition.
I have also noticed this issue, and I usually just add comments to document what is being inherited. If it were a language feature, you would probably also want a Restriction pragma identifier that would require its use, which does get a bit heavy handed.
The “overriding” keyword is essentially just a documentation feature, and serves a quite similar purpose, to allow the programmer to state their intent and have it checked by the compiler. It is analogous to an Assert pragma, where you are stating something that is believed to be true, and you want the compiler to verify your claim.
I do understand the concerns about verbosity, but when it comes to safety-critical software, being very explicit/redundant is the typical way to reduce the likelihood of latent errors.
Do you think it might be something the ARG would even consider if I started an issue on it (not necessarily any of the options I gave above, but any solution that helps)? The times it tends to hit hardest is when I need to extend a GUI widget that is like descendant level 6 in chain. Doing wrapper functions does work, but it is really error prone and it adds a lot of unnecessary visual bloat that doesn’t actually aid readability (in most cases it makes it worse since you now have 1000s of lines of code instead of a couple of hundred.
From a practical standpoint, we’ve historically had a few mistakes made due to copy/paste errors and those can be tricky to track down. Having an optional “annotation” syntax like overriding to indicate what subprograms are available would have eliminated most of those errors. I wouldn’t promote another keyword, but an aspect or creative existing syntax use would be good enough for me.
We welcome folks creating issues on the ARG GitHub site (Issues · Ada-Rapporteur-Group/User-Community-Input · GitHub). There is never a guarantee that the ARG will take any action, but it doesn’t hurt to present a problem that you have encountered with the language, and suggest some possible solutions.
I don’t see that being forced to use programming by type extension changes anything. The language forces it on you to achieve finalization. While ideally libraries should be rewritten to avoid it, there are limits to what can reasonably be achieved.
Note that I wrote Bar Code Drawing because I found the use of type extension in Ada Bar Codes difficult to understand. I find Bar Code Drawing much easier to undersand; hopefully that’s not just because I wrote it.
It doesn’t matter what level of soundness your reasoning has (none or perfect or in between). If you can’t be courteous to others in the way you present your reasoning and conclusion, then please don’t respond in this thread. There is zero need to take snipes at someone. The topic can be discussed without any of that.
You have a lot of good insights often, but it isn’t worth hearing them if you wrap it in belittling others.