[Oberon] Commenting code (was: Impartial observation? ...)

[Skulski, Wojciech]

Joerg:

> I think the indentation NW used helps a lot.

If I am not mistaken, the present code of this entire project is an automated translation from LOLA. (Thank you for pointing out the LOLA file.) It seems to me that NW wanted to relegate Verilog to being an intermediate assembly language which nobody should look at. He spent very little effort on cleaning it up.

If true, then this approach has flopped years ago. LOLA was never adopted anywhere outside ETH. There is a message in that rejection, which ETH school of thought never appreciated. My own opinion is that LOLA was meant to write Register Transfer Layer (RTL) code, which can be equally well written in Verilog or VHDL. An alternative way of writing such code was redundant. IMHO, lack of clear need was the reason why LOLA was ignored by the FPGA community. This community needs behavioral coding in order to lower the bar. Both Verilog and VHDL provided for behavioral code to some extent. Over a last decade, a very substantial effort went into High Level Synthesis and into graphical tools like System Generator. A low level RTL tool was heading in the opposite direction. Such a tool was not needed.

The nagging question in the entire FPGA industry was and still is "how to lower the bar of FPGA coding". Read the post by Jeff Maggio. The community in general, and our team in particular, need personnel who can get the job done. We do not need those who practice the faith, that the code should be terse, with few lines, abbreviated variable names, lack of clear coding rules, and lots of confusion. None of this is helping the goal. We rather need efficient tools, quickly writing good quality code, and reliable results achieved in short time. ETH coding faith is not helping at all.

The proof of the pudding is in the eating. Project Oberon could become such a proof if it was expressed in a way which an FPGA beginner can adopt and understand. Unfortunately, the opposite is true, as demonstratedby experts struggling with reading and understanding this code. Something is amiss, if the stated goal was education, while neither the students nor even the professors can easily follow the code.

> The only thing that is not clear by just reading it from the start is why the ternarys
> NW used are nested as they are. eg operation decoding in aluRes.
> This is pure time optimization running through log(N) multiplexers  instead of N.

The same optimization can be achieved with well written code. If-then-else is equivalent to the ternary coding. It would help with comprehension, if the same code was written with English keywords rather than C-like strings of seemingly random ()?: characters.

As a small example, why "disp" rather than "displacement"? Why "nxpc" rather than "next_PC"? Are we still living in the era of punched paper cards, or what?

> But these cascading multiplexers generate latency. Knowing that the seventh nxpc case
> is the most often used, „normal“ case and the other conditions are very rare, 
> NW nested the „IF“s (ternary ?) to reach nxpc the fastest, mainly after 2 multiplexers instead of 6.

All of that can be reached with rearranging if-then-else and using meaningful variable names. 

W.