W3C home > Mailing lists > Public > public-aikr@w3.org > May 2020

Re: For those who will venture into my code:

From: Paola Di Maio <paola.dimaio@gmail.com>
Date: Tue, 26 May 2020 13:38:02 +0800
Message-ID: <CAMXe=So=4x7Mn1kZB27EPH4DTg9qz=uXJa6oi=fRkL+DR5WNFA@mail.gmail.com>
To: Paul Alagna <pjalagna@gmail.com>
Cc: W3C AIKR CG <public-aikr@w3.org>

thank you

there was no link to the git!!!!!!

I never enjoyed writing code  but had the fortune to study with great great

I wa taught that a 'read me' file is fairly good practice with a
description of the code etc

really dont worry about it not being neat - scruffy is OK  however, keep in
mind that we all live on different planets
so any description of what the code is, how it is structured, how to run
in, your examples of what works and what not yet works etc
are necessary/ useful

I am not fussy but I do getphysically  sick and in a terrible mood when I
cannot comprehend something, cognitive dissonance has a physiological
effect on people
which is not good,   estetics as a feel good factor., as the coating for
bitter medicine

not fussy at all, but when it becomes necessary to ask too many questions
too many times
I necessarily have to give up and move on - have soo much work, my
attention is best devoted to things I can comprehend

I am used to do this with students, who are excellent at writing code that
nobody else can run let alone understand

My advice is:   imagine that you are sharing the code with someone from a
distant planet, who has no idea what
code is or how to use it.  For them a piece of code is like something they
have no idea what it is

you need to provide a description and also need to share all the
instructions to run it

a justification of your choices (why you did things in a certain wahy as
opposed to any other way)
is always welcome but often a luxury,

I am not even going to try to venture into looking any code until I see a
clear  enought and delectable description plus instruction on how to read
(a read me)

what is not delightful is not worth pursuing most of the time, this much I
have learned through painful lessons


On Tue, May 26, 2020 at 1:20 PM Paul Alagna <pjalagna@gmail.com> wrote:

> For those who will venture into my code:
> I tend to document as a comment in my code.
> Firstly is the plan of attack that I invision will take me from problem to
> goal and then as a diary of the nightmares that keep me up at night.
> I believe Edsger Dijkstra when he said any code or documentation beyond 2
> pages is humanly incomprehensible. I go even further that any documentation
> beyond 25 lines (the computer screen) is too big, usually because I packed
> too much detail.
> The control technique I have used here I affectionately call "umbrella"
> coding. This allows me to isolate sections of code as cleanly as I
> documented them. Well, that's the hope anyway.
> Sadly you may find that sections of the "diary of nightmares" is out of
> sync with the actual code. The method should be code, test, document,
> repeat, but doing battle on many fronts tends to wipe out my good wishes.
> Thanks
> PJAlagna@Gmail.com <PJAlagna@gmail.com>
> 732-322-5641
Received on Tuesday, 26 May 2020 05:38:52 UTC

This archive was generated by hypermail 2.4.0 : Tuesday, 26 May 2020 05:38:53 UTC