Threaded Mode | Linear Mode

pier4r · 01-21-2018, 03:34 PM

(01-21-2018 02:32 PM)peacecalc Wrote: 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.

It is. But some variation is also allowed or not? Or "Real forum users" don't variate from the main topic?

I mean the comments are about humorous documents that include taunts to absence of documentation, therefore they encourage to do the opposite (document properly).

At least for what I understood.

Maximilian Hohmann · 01-21-2018, 04:04 PM

(01-21-2018 03:34 PM)pier4r Wrote: At least for what I understood.

You understood perfectly well.

Many years ago I was involved in some software development where the contract stated that the source code had to be supplied to the client. As the owners of the little company which subcontracted me on this project really didn't like their clients to have the source code (which was their main capital so to say) I got the task to make it as unreadable as possible. So I wrote a little program (in C or FORTRAN, can't remember) which stripped the source code from all comments, renamed all variables and functions to "VAR001"..."VAR999" (with the numbers in random order and leaving gaps between the numbers) and "FUN001" to "FUN999". By that the contract was fulfilled (the clients were able to compile the code themselves) but the code itself was next to useless because figuring out what it did and how would have been more expensive than contracting us again for future development.

**rprosperi** · 01-21-2018, 05:10 PM

(01-21-2018 03:34 PM)pier4r Wrote: ...Or "Real forum users" don't variate from the main topic?

Yes, you understand perfectly. Wink

badaze · 01-21-2018, 05:40 PM

(01-21-2018 04:04 PM)Maximilian Hohmann Wrote:
(01-21-2018 03:34 PM)pier4r Wrote: At least for what I understood.

You understood perfectly well.

Many years ago I was involved in some software development where the contract stated that the source code had to be supplied to the client. As the owners of the little company which subcontracted me on this project really didn't like their clients to have the source code (which was their main capital so to say) I got the task to make it as unreadable as possible. So I wrote a little program (in C or FORTRAN, can't remember) which stripped the source code from all comments, renamed all variables and functions to "VAR001"..."VAR999" (with the numbers in random order and leaving gaps between the numbers) and "FUN001" to "FUN999". By that the contract was fulfilled (the clients were able to compile the code themselves) but the code itself was next to useless because figuring out what it did and how would have been more expensive than contracting us again for future development.

I know some programers who do not need to write any software to make incomprehensible code. They have it in ROM !

toml_12953 · 01-21-2018, 09:04 PM

(01-21-2018 04:04 PM)Maximilian Hohmann Wrote:
(01-21-2018 03:34 PM)pier4r Wrote: At least for what I understood.

You understood perfectly well.

So I wrote a little program (in C or FORTRAN, can't remember) which stripped the source code from all comments, renamed all variables and functions to "VAR001"..."VAR999" (with the numbers in random order and leaving gaps between the numbers) and "FUN001" to "FUN999". By that the contract was fulfilled (the clients were able to compile the code themselves) but the code itself was next to useless because figuring out what it did and how would have been more expensive than contracting us again for future development.

I hope you kept an unmodified copy for your future use!

brickviking · (This post was last modified: 01-21-2018 10:49 PM by brickviking.)

(01-21-2018 08:36 AM)peacecalc Wrote: Hey folks,
...

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

I suspect we'd never be able to run the tools on the metal though, we'd have to use a computer to do that. Perhaps the two utilities could be rpltngl and rplwv?

(Post 155)

brickviking · 01-21-2018, 10:48 PM

(01-21-2018 04:04 PM)Maximilian Hohmann Wrote:
(01-21-2018 03:34 PM)pier4r Wrote: At least for what I understood.

Many years ago I was involved in some software development where the contract stated that the source code had to be supplied to the client. As the owners of the little company which subcontracted me on this project really didn't like their clients to have the source code (which was their main capital so to say) I got the task to make it as unreadable as possible. So I wrote a little program (in C or FORTRAN, can't remember) which stripped the source code from all comments, renamed all variables and functions to "VAR001"..."VAR999" (with the numbers in random order and leaving gaps between the numbers) and "FUN001" to "FUN999". By that the contract was fulfilled (the clients were able to compile the code themselves) but the code itself was next to useless because figuring out what it did and how would have been more expensive than contracting us again for future development.

I just thought of something a little more evil than that. You could have used one of the C obfuscation contest programs as inspiration. Heh.

(Post 156)

Thomas Okken · 01-21-2018, 11:28 PM

(01-21-2018 04:04 PM)Maximilian Hohmann Wrote:
(01-21-2018 03:34 PM)pier4r Wrote: At least for what I understood.
Many years ago I was involved in some software development where the contract stated that the source code had to be supplied to the client. As the owners of the little company which subcontracted me on this project really didn't like their clients to have the source code (which was their main capital so to say) I got the task to make it as unreadable as possible. So I wrote a little program (in C or FORTRAN, can't remember) which stripped the source code from all comments, renamed all variables and functions to "VAR001"..."VAR999" (with the numbers in random order and leaving gaps between the numbers) and "FUN001" to "FUN999". By that the contract was fulfilled (the clients were able to compile the code themselves) but the code itself was next to useless because figuring out what it did and how would have been more expensive than contracting us again for future development.

I guess your customer didn't really care about that code, or they were too nontechnical to realize they were being swindled... because that sabotaged version of the code you're describing there does not satisfy any sane interpretation of "supplying the code" that I can think of. You were certainly not handing over the code that you actually worked on.

peacecalc · 01-23-2018, 09:14 AM

Hello brickviking,

Quote:original from brickviking

I suspect we'd never be able to run the tools on the metal though, we'd have to use a computer to do that. Perhaps the two utilities could be rpltngl and rplwv?

But the hp 50g has the power for such a project, source text as a string, defining meta sign for source code ... Input that string in "rpltngl" and we get a program for the calc, and if we input the string to "rplweave" we get the documentation for that program.

But I've the impression, that this kind of programming: "literate programming" isn't used much by professionals. Is this right?

brickviking · 01-24-2018, 08:00 AM

(01-23-2018 09:14 AM)peacecalc Wrote: Hello brickviking,

Quote:original from brickviking

I suspect we'd never be able to run the tools on the metal though, we'd have to use a computer to do that. Perhaps the two utilities could be rpltngl and rplwv?

But the hp 50g has the power for such a project, source text as a string, defining meta sign for source code ... Input that string in "rpltngl" and we get a program for the calc, and if we input the string to "rplweave" we get the documentation for that program.

But yes, if the calculator could actually do a rplwv or rpltngl, that could open the door to calculator programs with included help, all from the one source file.

(01-23-2018 09:14 AM)peacecalc Wrote: But I've the impression, that this kind of programming: "literate programming" isn't used much by professionals. Is this right?

I wouldn't know, I've never been "professional". I'm actually a caregiver for my wife, but computers, calculators and (currently) flight simulation are my current excursions into keeping myself engaged.

(Post 159)

Thomas Okken · 01-24-2018, 11:38 AM

(01-23-2018 09:14 AM)peacecalc Wrote: But I've the impression, that this kind of programming: "literate programming" isn't used much by professionals. Is this right?

I am a professional, but of course the experiences of one person still don't make much of a survey. For what it's worth, the only place where I've ever seen Literate Programming is in the TeX source code.

pier4r · 01-24-2018, 12:26 PM

(01-23-2018 09:14 AM)peacecalc Wrote: Hello brickviking,

But the hp 50g has the power for such a project, source text as a string, defining meta sign for source code ... Input that string in "rpltngl" and we get a program for the calc, and if we input the string to "rplweave" we get the documentation for that program.

But I've the impression, that this kind of programming: "literate programming" isn't used much by professionals. Is this right?

It is always a matter of tradeoff. There are people da do amazing projects over years: see hpgcc, newrpl from claudio and all the things for the 41. Anyway hp calculator (and calculator in general) activities have to compete with other activities for the time spent because likely no one will pay enough for such projects.

For example I spend my little time on some little math problems and comments rather than writing a software to make comments easier. One has to start small and comments plus a little description for me are way enough.

Therefore while I would be amazed by a person doing what you propose, I also think very few have the time to do it.

For my experience in IT, I saw also very few programmers documenting commercial projects.

3298 · 01-24-2018, 05:12 PM

All this talk about mixing source code and docs reminds me of Doxygen, which is a popular tool for just that. HPGCC3 uses it, to name just one HP-related example. (Here's the extracted documentation.)
A very convenient feature of the Doxygen system is that the documentation is stuffed into the programming language's comments, which turns source code extraction a no-op. (Sure, you could strip out the comments, but what's the point when the compiler will ignore them anyway?) Being mostly text-based, the documentation often doesn't have to be extracted either to be helpful. Some lazy programmers (including myself) simply read the comments containing the documentation instead. The plain-text editors used for editing the source code usually don't help in presenting the documentation in a nice way (beyond some basic syntax highlighting for Doxygen's keywords), so you lose the markup, any embedded images will have to be found and opened by the user, and all references need to be manually searched for, but most of the time the pure text in a comment preceding a function is enough to understand the function's code. If it isn't, then chances are that the full documentation rendered into HTML pages won't help either, in which case you better yell at the original author to provide proper docs, or bite the bullet and just try to follow the code.

In the end, everything just boils down to writing useful comments into the source. If you want to be nice, you format them for Doxygen so the weirdos who want some pretty docs can extract them, but I'd call even that optional. Putting the documentation as close as possible to the code it documents is the more important thing, because it keeps the programmer and later maintainers from getting distracted and/or annoyed at the constant switching between code and doc while writing / reading these. Some additional higher-level introduction or explanation of concepts for more complex pieces of code can go anywhere really, as long as it's easy to find for those who need it (e.g. at the top of the main source file relevant to the topic - or for the smaller snippets that started this discussion: before or after the entire code).

For our beloved HP calculators, I'd rate onboard doc-extracting programs as unnecessary. You can't easily switch between docs and code, so having the docs embedded into the code as comments is the most useful way. When there is another device nearby that can display separate documentation (e.g. a PC), that becomes less true, but since the documented code probably has to pass through that device to get into the calculator, it would be more fitting to use existing doc extraction tools on that device instead, if at all. So keep documenting your RPL with embedded raw text comments and/or forum posts, and all is well.