[Oberon] Cleaning up low level modules (a pipe dream)
joerg.straube at iaeth.ch
Fri Jun 19 23:05:28 CEST 2020
An approach with one file - although the intention is good - is NOT good.
In big contrast to C includes (.h files) - where your idea might stem from - compiled Oberon modules have strongly enforced version keys.
The consequence of having ONE file, is, whenever you add some new constant to it, you have to recompile ALL sources, link the inner core, basically re-build the whole Oberon system, only because you added eg LF* = 0AX to your constant collection.
Such an approach destroys the whole Oberon idea of separate compilation.
Whenever the constants are so important that you want to export them, you anyhow have to give them a name.
When the constants are internal to a module, you might name them or you might not. Because it‘s internal the scope and meaning of this constant is very local and not of importance to the rest of the system.
Your base idea is okay, but please not in ONE file. Group the constants by area. Eg move all ASCII constants to Input.Mod. It is really strange that all modules working with ASCII redefine the constants over and over again instead of just importing them from one central place namely, Input.Mod (I did that and defined also ASCII codes of the arrow keys, I can move the caret with the keys and not only the mouse)
Group all memory related constants to Kernel.Mod, group all your file system related constants to Files.Mod, group all your timer related functions to either Kernel.Mod or write a new module Timer.Mod. But please don‘t use ONE file, where all your constants are in. I grouped all Wiznet related constants to W5500.Mod, I grouped all IP related constants in IP.Mod and so on.
And if you need them you just write
IMPORT Kernel, W5500, IP;
and use them IP.AnyPort or W5500.InterruptMask...
> Am 19.06.2020 um 22:18 schrieb Skulski, Wojciech <skulski at pas.rochester.edu>:
>> Please don't.
> My proposition was a tongue in cheek. But the goals/motivation are serious. While everyone seems to agree that it would be good to have a clean code base, then everyone is also unwilling to touch upon the 2013 Oberon System sources. It is a chicken and egg problem. This particular egg cannot hatch a strong and healthy chick. But it cannot get improved either for some strange reason.
>> Look how the low level modules are written in Astrobe. They are readable.
> Astrobe is different by design, thank goodness.
>> Better to invest time in writing a writer in Oberon than importing C.
> Importing C was a little joke.
>> Could you give an example of the messy lowlevel modules your are mentioning?
> I will e-mail you a detailed account to your private e-mail, since the list is hesitant of attachments.
> Half joking I have proposed the Hercules project to maybe help a little bit. Here is the description from my web page.
> Hercules: The Oberon Source Code Cleaner and Sanitizer
> Synopsis. Any software system can benefit from following programming rules, such as neat formatting, consistent naming conventions, avoidance of tricky uncommented code, informative comments, and avoiding numerical constants written directly into the source code. In the C world the programming rules are routinely enforced by both the development tools and by the elders of the tribe, to a great benefit of the C community. I can only wish that the same was true with Oberon.
> Hercules is the name of the proposed automatic cleanup tool to help achieve better code quality. It will be an Oberon module which will take some other module, factor out all the verbatim numerical constants, and replace them with symbolic names. The list of both the names and their numerical values will be named SysDef.Mod. Such a definition module, whose goal is similar to a C header file, will become a part of the Oberon System interface definition. Its main role will be factoring out hardware, firmware, and software interface addresses, which are holding values such as display resolution, refresh rate, serial link speed, etc. We can start with a single such definition module. At present, the FPGA Oberon System is simple enough that one file will be sufficient. More such definition modules can be introduced in the future, factoring out interfaces of various hardware or firmware subsystems.
> Hercules will act as a prefilter. As soon as a new or a modified Oberon source gets published on the web, we will be able to apply Hercules to it and then adopt the cleaned up code. Since this issue persists for the whole Oberon history, this tool may also be named Sisyphus. I am not yet sure which name is better. It is much needed anyway.
> Oberon at lists.inf.ethz.ch mailing list for ETH Oberon and related systems
More information about the Oberon