[libre-riscv-dev] mypy type annotations for nmigen

[Jacob Lifshay]

On Tue, Mar 12, 2019, 22:12 Luke Kenneth Casson Leighton <lkcl at lkcl.net>
wrote:

> On Wed, Mar 13, 2019 at 4:55 AM Jacob Lifshay <programmerjake at gmail.com>
> wrote:
>
> > I created some type annotations for nmigen:
> >
> >
> https://salsa.debian.org/Kazan-team/simple-barrel-processor/tree/master/mypy_stubs/nmigen
> >
> > to use, add mypy.ini and mypy_stubs to repo root and run mypy or use pyls
> > (python language server) with pyls-mypy
> >
> > If we're going to use this much, we should put the nmigen type
> annotations
> > in a separate repo so it's easier to update across all users.
> >
>
>  i'd like to understand the benefits, first.  the separation seems like a
> significant disadvantage, forcing people to write large amounts of
> unnecessary code (the static typing) where, ordinarily, the code (dynamic
> code) would be compact and minimal, and unit tests - which are an absolute
> essential prerequisite - will catch errors and provide confidence in
> correctness.

the nmigen type annotations are separated so we don't have to rewrite
nmigen. All of the code I've written that uses nmigen has the typing inline
in the function/variable definitions.

One major gap in the typing annotations for nmigen is that when you write
to .submodules, since you're adding variables that aren't in the definition
of .submodules, it can't type check them (from what I understand). I've
left .submodules typed as Any for that reason, since Any basically tells
mypy to turn off type checking for that variable.

Note that mypy can deduce the types of most variables correctly, so type
annotations are usually only needed on function parameters/return values.

One of the benefits of static typing that I've already used is much better
auto-completion of member variables/methods, reducing development time a
lot for me.

I think that pyls can be used with vim, so you can get auto-completion, go
to definition, type checking as you write, code formatting, and more.

to use mypy with that, install pyls-mypy using pip with python3.

>
>  i appreciate that you're used to strongly-typed languages (i started out
> with c / c++), i'd like to know that there is an *actual* demonstrable
> benefit, before resources are committed.
>
>  specifically: if the typing catches 0.5% of bugs (bugs which are caught
> anyway through comprehensive unit tests) yet adds 40% extra in development
> time, that's not a benefit, it's a very strong case *not* to spend the time
> (and money).
>
>  if on the other hand it can be demonstrated that static typing catches 80%
> more bugs, for only requiring 10% of extra development effort, or it
> *reduces* the amount of code needed to be written, that's a clear benefit.
>
I don't know how much it reduces bugs since I don't have enough experience,
but, for me, it actually decreases total development effort because of
auto-completion. If I was writing the code without auto-completion, I'd
estimate that static typing increases the effort required by a few percent
since in a lot of cases the only annotations required are on function
definitions and they tend to be simple.

>
>  as i explained in the previous message: given that we are using nmigen,
> and that nmigen is itself not using static typing, the benefits are not
> clear.
>
I added the static type annotation files (*.pyi) so mypy can work with most
nmigen code as if nmigen was statically typed.

>
> can you demonstrate *clear* benefits for the effort that is projected to be
> expended, or demonstrate that the effort to be expended is minimal and
> effective?
>
for me, yes. For everyone else, that depends on if they are using pyls or
not. In any case the effort required seems minimal, and I found it to be
effective for me.

Jacob