Re: NVDA development: Making sure NVDA source code/API documentation becomes one of the greatest out there in helping new developers

Brian's Mail list account <bglists@...>

Yes my experience exactly. Having been in both sides of the equation I do understand where folk come from.
In the old 8 bit days when i was sighted, I also had the problem that hardware was very very different between machines even if the processor was the same of course, and you had two lots of people, those who wanted to make a core and then add the hardware support to that and those z80 assembler folk who wriote it from the ground up and it then could never be ported to anything else without several nervous breakdowns and lots of tantrums..:-)
and then ther was CP/M ahem.
At least these had routines you called which were standard as far as what the input and output was on all platforms, only the operating system itself needing the bespoke drivers of hardware.

Bit restrictive on use of hardware specific enhancements though.

Anyway off topicnow so off for a lie down.

Sent via blueyonder.
Please address personal email to:-
briang1@..., putting 'Brian Gaff'
in the display name field.

----- Original Message -----
From: "Brian Vogel" <@britechguy>
To: <>
Sent: Wednesday, December 21, 2016 3:36 PM
Subject: Re: [nvda] NVDA development: Making sure NVDA source code/API documentation becomes one of the greatest out there in helping new developers

On Wed, Dec 21, 2016 at 02:19 am, Brian's Mail list account wrote:

However, I suspect that most people when writing code kind of get it as a
flash of inspiration or stream of consciousness then debug it from memory
and then forget by the end what in fact needed to be commented as they
understood it themselves so to speak.
Yes, this is a tangent, but a closely related one. I can absolutely relate to getting a top-down "how I'm going to do this overall" flash of inspiration with regard to programming solutions. My period of time for that was traditionally just before I dropped off to sleep, which is why I got in the habit of keeping a notepad handy to write down what that flash of high-level inspiration was. If I had just a very brief note I could generally bring it all back the next day, but often if I had nothing the only thing I could recall is that I'd had a flash of insight but no functional recollection of the nature of that insight.

But the coding itself was still, even when it was utterly fluid, something that I self-taught myself to comment when it was being written in terms of what the code segment that followed a comment was intended to do at whatever functional level made sense for the comment. It was never a "line by line" thing.

One can, with great personal effort, get in that habit. One can also, as a project lead, with great effort (and, usually, a period of being intensely "hated" by those you're supervising), create a culture where commenting is a must. Rejecting great, big, hundreds-of-lines of code with nary a comment, even if it works perfectly, is often required. I have yet to find those who are focusing the hatred during the period where this is new not coming round to bless the person who forced the issue when they have to come back in say, six month's time or longer, and try to update that code in some way. There always seems to be a period of intense struggle, though, as the "I don't need to comment my code - it's self evident" crowd persists in that delusion and that delusion is strong.

* Life is the art of drawing sufficient conclusions from * *insufficient premises.*

* ~ Samuel Butler, 1835-1902*

Join to automatically receive all group messages.