Hi, I just had an idea (that may be terrible :/) that could help slightly
refocusing the thread.
I completely embrace the idea that in this day and age, there are trade-offs
that are no longer worth it. But once again, there is Github and the rest... No
grep there...
So instead of forcing the developer to put hints (e.g. explicit module names)
for future readers to understand the code structure more easily, why not having
the compiler do that for you? So my suggestion (which again, might be a very
very bad one and it is fine to say so) would be to have **compiler comments**
(in the source code).
These comments could be autogenerated at each compilation/commit and introduced
by a _different symbol_ than comments provided by the developer. The use of a
different symbol brings nice properties: the compiler doesn't have to guess
what was generated by itself, it knows it; the user is warned that changing
such comments is useless; there is no overlap between what the developer wrote
and what the compiler added and more importantly, the very first thing a
Nim-aware IDE could do is to strip them (as such comments would provide
inferior, but otherwise useful hints).
Such comments could be used for instance to emulate explicit imports but only
as needed:
import Foo
discard add_two_and_display(5)
**could** be translated to something like this (taking "!@ .. @!" to declare
compiler comment):
import Foo
!@ add_two_and_display(int): int -> Foo/bar/baz.nim @!
discard add_two_and_display(5)
As the compiler knows about all things, such compiler comment should obviously
**not** list every symbol exported by the module, but just the ones actually
used. Since it is generated at each compilation, the list can be kept up to
date. And obviously this kind of things:
import Foo
discard Foo.add_two_and_display(5)
should not generate any compiler comments since the hint is already there,
provided directly by the developer.
Likewise, such concept could be extended to other areas in the program (e.g.
state what is returned from a procedure if there is no explicit return
statement or the result of executed code at compile time like in when
statements)... or not... (again, I don't see everything: the idea could be very
bad).
The few negative points about this that I can see are:
* This can be very verbose, but again maybe not (that may encourage better
behaviours though).
* These comments should be made reproducible so that the diffs stay nice and
to the point.
* For this to be effective, a minimum amount of auto-commenting should be
provided by default (with a flag/pragma to disable them maybe). That means that
the compiler itself should handle that instead of a third-party tool. But at
the same time, some systems/IDEs may not be too happy if some other program
modifies the sources currently loaded.
The last point is obviously the main problem with the approach. But again,
modern IDEs and text editors may behave better than what I think.
