Sharing is caring, thanks for your code, but....

[pier4r]

So I was reading this discussion:
(1) http://www.hpmuseum.org/forum/thread-9955.html

then landed on this:
(2) http://www.hpmuseum.org/forum/thread-9919.html

and finally on this:
(3) http://www.hpmuseum.org/forum/thread-9973.html

I think that sharing code is great. Having sources is somewhat better than having only the binary, since one can work on the sources. Of course having sources and binary is even better. In any case sharing something is better than sharing nothing.

Nonetheless one can see that insights about the algorithm exposed in (3) are mentioned in (2), but are not reported in (3). In general more often than not the source code that gets published here is a sort of black box. One can use it, without really understanding why it is in that way. There are some examples how to use it and stop.

Comments or descriptions are almost non-existent. That is a pity sometimes, because some programs either cover some interesting topics or contains some pretty techniques that one may not notice without analyzing the code intensively. One may even decide to say "ah nice idea, although I'd like to understand the procedure. This code looks cryptic, I do it my way and then I might use this piece of code as comparison".

With comments or descriptions one can notice techniques or pointers to this or that topic a bit better.

[Joe Horn]

Excellent suggestion. The posting in (3) has been updated to include references to (1) and (2).

EDIT: And inline comments have been added. But please keep in mind that programming is my HOBBY, because programming is great fun, but writing comments and documentation is FAR less fun. I'd rather answer specific questions (which reveal the delightful fact that SOMEBODY even CARES about my code) than wasting un-fun hours writing comments and documentation which -- for all I know -- nobody even reads.

"Paranoia is the comforting delusion that somebody is thinking about you." -- seen on a bumper sticker

[pier4r]

This http://www.hpmuseum.org/forum/thread-9973.html is now (thanks Joe) a really good example of what would be great to see alongside the shared code.

At least for my perspective.

- examples? Check.
- code? Check.
- Comments? Check.
- step by step explanation or just an explanation? Check.
- description of the input? Check.

Of course I know that it takes time to add everything (I myself don't do it), but one can add a piece after another over time.

edit:

Quote:"Paranoia is the comforting delusion that somebody is thinking about you." -- seen on a bumper sticker

I am stealing this!

And yes I know that writing documentation is not that fun (but is crucial to reuse the code). Nonetheless one may also realize that posting cryptic code may hinder questions that instead would arise from a less cryptic exposition of the procedure. I would say that adding the code and then adding at least a description of the idea (not necessarily in comments, a block of text aside the code is enough) already raises the chances that one gets interested in the code.

Second observation: people get interested over time. Not everyone is on the same topic on the same moment.

[Maximilian Hohmann]

(01-20-2018 09:25 PM)pier4r Wrote:  And yes I know that writing documentation is not that fun (but is crucial to reuse the code).

Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

[brickviking]

I'm still new to RPL—and somewhat new to programming in general even after twenty five years, and sometimes what's obvious to most others (that may have been programming for a while) isn't obvious to me. One way for a new user to gain facility is to spend time each day basically gutting small routines, working out how they work. Heck, write it down on a piece of paper step-by-step if you have to, that's exactly how I had to debug one of my recent routines.

After six months of doing this, you should have a better idea of what functions do, and more importantly, how they can be glued together to provide more extended functionality, which is the real benefit. Keepng up with this for more than a couple of years should mean you'd get pretty good. Of course the AUR is pretty good at helping out in this regard, as it describes things at the statement level, and also has a small section describing how to use the language. The HLP49 library can also describe functions (not as detailed as the AUR) but often provides little source code snippets that perform useful functions that include what's being looked up.

That's why I like this forum and the files site, it's a valuable resource; far more detailed than one other Casio offering I've used. I'm not sure how it compares to other calculator sites like cemetech or tiplanet.

(Post 154)

[Massimo Gnerucci]

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  

(01-20-2018 09:25 PM)pier4r Wrote:  And yes I know that writing documentation is not that fun (but is crucial to reuse the code).

Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

Real Programmers Don't Use Pascal

[rprosperi]

(01-21-2018 02:11 AM)Massimo Gnerucci Wrote:  

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

Real Programmers Don't Use Pascal

Thank you Massimo!! Just 2 weeks ago I was searching for this seminal work, one of the first to popularize the act of dubbing those who don't measure up as "quiche eaters". Funny how little things have changed over the years...

[Paul Berger (Canada)]

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  

(01-20-2018 09:25 PM)pier4r Wrote:  And yes I know that writing documentation is not that fun (but is crucial to reuse the code).

Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

"It was hard to write, it should be hard to read"

[Thomas Okken]

(01-21-2018 03:00 AM)rprosperi Wrote:  

(01-21-2018 02:11 AM)Massimo Gnerucci Wrote:  Real Programmers Don't Use Pascal

Thank you Massimo!! Just 2 weeks ago I was searching for this seminal work, one of the first to popularize the act of dubbing those who don't measure up as "quiche eaters". Funny how little things have changed over the years...

I vaguely remember reading about this book, "Real Men Don't Eat Quiche," back in the early '80s. As I recall, it was tongue-in-cheek, which was just as well, because the gist of it was: if you're a man, you're not supposed to like anything that women like.

How dumb is that? And besides, quiche is great. Quiche Lorraine, especially, but other kinds, too. Dutch people should know this, even though they don't usually call it quiche, they say "hartige taart." Good stuff.

Real men don't care about what makes a real man a real man.

[peacecalc]

Hey folks,

that is the oppertunity to give a hint to Donald E. Knuth "Literate Programming". With the program TeX and the extension WEB you are able to mix source code of a programming language and the descriptive text. Second condition is that you use the source code part in a order which is usefull for documentation, if you strip the documentation text, the source code has the right order. And last not least WEB is able to produce a full docmentation with crossreferences and a table of contents.

WEB was developped for "PASCAL" later on came CWEB for "C". Maybe somebody has time and interest enough to develop RPLWEB.

[pier4r]

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

I hope it is sarcastic. I am not sure though.

We could consider whatever calculator as library of function (triggered manually). Aside from the most basic functions, that one can discover via some trial and error*, I wonder how can one figure out RPN, RPL or whatever slightly complicate and large library of functions without documentation or examples. (same for every other non trivial framework, be it assembly, fortran, pascal, java, c#, javascript, php, heck the OSes themselves)

Unless we develop a way to exchange information mind to mind (and even that there would be information exchange), to understand what the other did one needs some (proper) documentation. Even if the other is "ourselves from the past".

* But then again, we could use the function, say "power" because we got the information how the power function works from other sources.

[Paul Dale]

We need to bring back Rambotran. The only true programming language.

[Maximilian Hohmann]

(01-21-2018 11:26 AM)pier4r Wrote:  I hope it is sarcastic. I am not sure though.

Don't worry :-)

In that document it also says "Real programmers don't wear high heel shoes" which is really a pity because next to nothing has changed in this respect over the last 40 years. Just look at this forum!

[TheKaneB]

(01-21-2018 11:38 AM)Paul Dale Wrote:  We need to bring back Rambotran. The only true programming language.

I prefer self-documenting code like this

[Paul Dale]

I've tried high heels, they are far too difficult and uncomfortable to walk in


Pauli

[cjmcc]

(01-21-2018 03:51 AM)Paul Berger (Canada) Wrote:  

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

"It was hard to write, it should be hard to read"

My favorite line was always, "Real programmers can write FORTRAN in any language."

[pier4r]

(01-21-2018 11:56 AM)Maximilian Hohmann Wrote:  Don't worry :-)

In that document it also says "Real programmers don't wear high heel shoes" which is really a pity because next to nothing has changed in this respect over the last 40 years. Just look at this forum!

Yes indeed. I observed the lack of high heels pictures here.

(01-21-2018 12:00 PM)TheKaneB Wrote:  I prefer self-documenting code like this

this cracked me up at

Quote:Equal to

YOU ARE NOT YOU YOU ARE ME operand

[Massimo Gnerucci]

(01-21-2018 11:26 AM)pier4r Wrote:  

(01-20-2018 10:16 PM)Maximilian Hohmann Wrote:  Many, many years ago, a document called "Real Programmers" made it's rounds around ARPANET and other predecessors of the internet. I must have it somewhere but not on the computer I use right now. But I fondly remember one of it's basic dogmas because I kept repeating that to clients in the days I got paid for writing software:

Code:

Real prgrammers don't write documentation. The code is obvoius.

I hope it is sarcastic. I am not sure though.

ABEND

;) <- sarcasm

[rprosperi]

(01-21-2018 08:05 AM)Thomas Okken Wrote:  I vaguely remember reading about this book, "Real Men Don't Eat Quiche," back in the early '80s. As I recall, it was tongue-in-cheek, which was just as well, because the gist of it was: if you're a man, you're not supposed to like anything that women like.

How dumb is that? And besides, quiche is great. Quiche Lorraine, especially, but other kinds, too. Dutch people should know this, even though they don't usually call it quiche, they say "hartige taart." Good stuff.

Real men don't care about what makes a real man a real man.

Indeed, the book was (not really too subtly) poking fun at the "Real men don't ..." crowd, just as I believe that article was poking fun at those preferring Fortran and/or toggling console switches as the only viable solutions to all programming problems. That said, they are both rich with insightful humor and good examples.

However, the reference that "Real programmers can write FORTRAN in any language." was an all too real phenomenon, that sadly has not improved as much as the gender situation has.

[peacecalc]

Hello friends,

it seems to me I misunderstand this thread. I thought it would be a seriuos examination about a good way to share and to document code. My only apology is that I'm not mother-tongue speaker (and reader, writer) in English.