[Libre-soc-dev] SimdSignal library

[lkcl]

On October 3, 2021 4:32:38 AM UTC, Jacob Lifshay <programmerjake at gmail.com> wrote:

(i deleted context by mistake, apologies)

part of the time estimates for a task should naturally include the time needed to communicate and read other communication.

by not reading the mailing list messages, this actually cost time, not saved time, didn't it?

my feeling is, here, it may be valuable for you to write out a series of howtos / FAQs (with a doc budget attached).  a checklist of steps and insights, starting with:

* "i have an idea" ==>
    action to take: raise a bugreport and cf mailing list
* "i feel this is important to implement right away" ==>
    action to take: activate "time / budget analysis, risk assessment and maintenance evaluation process"
* "i am writing some code right now" ==>
   action to take: check coding standards and procedures

we're getting big enough that these things really ought to be written down, and also, i know that it helps enormously with Asperger's to have a list of simple and set "procedures".  they're defined, therefore they're predictable, and therefore comfortable, familiar, and no freaking out occurs. which i do a lot, myself.


>it constructs a dict mapping lanes to tuples of slices of signals, by
>nesting essentially a list-comprehension inside a dict comprehension.
>each
>element of the tuple is a sliced signal, where the slice is
>lane.translate_to(layout).as_slice()

list incomprehensions are a deeply problematic part of python that should never have been added.  they cause the reader to have to think backwards and defer understanding until the very end of the sentence.

nested incomprehensions are even worse.

adding *yet another* layer of incomprehension by smashing in obstructive type information right in the middle makes for *three* levels deep of incomprehension.

added to that three different types of brackets nested four times and it's no wonder the code's completely illegible.

[it took me about 45 seconds to spot the *one* symbol difference between those two pieces of code.  that's really shocking]

english is left to right.

list incomprehensions interrupt that natural reading order.

please therefore for goodness sake don't nest them.  use an explicit for-loop or map, even if it's more code.

map comes FIRST when read from left to right.  you know, immediately on seeing the word "map", that something is, in fact, going to get mapped, in the immediate future, as you continue left to right reading.

with map, the action - the context - precedes the things *being* acted on.

list incomprehensions leave you wondering what the bloody hell is going on.

if you must insist on using list incomprehensions please *only* do so if the entire incomprehension fits onto a single line.

in exceptional circumstances split it across two lines: the object being repeated on one line and the incomprehensible list part directly underneath it,
lined up vertically.

we're writing extremely complex long-term code, here. anything that actively interferes with readability is a huge risk.


>>  if i've been using python for 21 years and can't interpret that,
>it's
>> a bad sign.
>>
>> there's no code comments - at all - so i have absolutely no idea what
>> the code is doing.
>>
>
>well...the type annotations are part of the documentation...following
>the
>types should get you 90% of the way there.

no chance.  absolutely none.

comments are deliberately written in english and should outline both the intent and the thoughts going through your mind at the exact moment the code is written.

they explain *why*, and also sometimes "how".  comments do not explain *what* because that is what the code itself does and is for.

they also *precede* the code - not interrupt it in the middle - so as to provide necessary context on which to "hang" what is going to be difficult non-natural mathematical abstract thought.

type annotations - which i find are an unproductive waste of time that actively interferes with readability due to interrupting the natural left-right flow - describe *what*, not how, and certainly not "why".

the human brain is primarily triggered by "why", followed only by "how" and finally "what". Simon Sinek's Ted Talk covers this extremely well.



> Assuming you're using an IDE
>that shows variable types 

this isn't a reasonable assumption to make.  i stopped using IDEs for software development in 1995 (visual studio msvc)

> (vim should be able to do that by using pyls
>or
>similar language servers), following the types is quite easy, assuming
>it
>can still see type annotations somewhere.

1) i'm not interested in doing so because they don't answer *why*.  the type is *completely irrelevant* because of the Liskov Substitution Principle.

if i want to know the functions i'll open up its file in a separate xterm [which does not transfer mouse hover or other commands to vim, and i am very happy that it does not. to the point where, if it did, i would find a way to permanently disable it]

if i don't know its type i can look where it is instantiated, get its type, check the import, and open up the file *and leave it open*.

if i can't find it because it's instantiated by a base class, i use recursive-grep, then open up that file too.

2) due to short-term memory problems a popup with some "type" is utterly useless.

i would LITERALLY spend hours per day taking my hands off the keyboard and onto the mouse to hover repeatedly in an endless loop over things i cannot retain.

ONLY by having MULTIPLE files open on-screen simultaneously have i been able to work around severe short-term memory and learning difficulties.


as the person who is directly responsible for understanding every single one of the moving parts of this immensely complex project, it is rather unfortunately slightly embarrassing to have to say that everyone else really does have to fit within and work around the limitations that i myself have to accept and cope with.

the massive reliance on the bugtracker, code comments and the wiki is not there "just for fun or because i read somewhere it's supposed to be a good idea", it's because i literally couldn't cope without them.

and that in turn means that anything that doesn't fit within that, i can't review it and sign it off.

we're long past the prototyping phase where things can be rushed, basically.

l.