A Catalogued Collection of Annotated Examples

[kmj]

I've got this cool idea; of course, I usually never get around to implementing my cool ideas, but I think it would be awesome if something like this existed:

If there a Catalogued Collection of Annotated Examples for Programming for various languages.

Catalogued: Each example program would have a list of topics it deals with: (pointers, sockets, using "const", etc.) Perhaps 1st in the list would be the major topic, 2nd would be next highest, down to things that are just in there incidentally near the bottom of the list. There would then be a search which would report examples which had the keywords higher on their lists first. So people could say, "I want to learn about sockets", and they'd get a list of examples that deal with sockets; at the top would be those which had sockets first, at the bottom would be those which had sockets last.

Collection: A big collection of these example programs. Indexed alphabetically, by topic, and catalogued as mentioned above.

Annotated: The author would thoroughly comment his code describing exactly what he was doing and why he was doing it, perhaps mentioning some other implementations and discussion why he chose the one he did. Basically, you can get as complex as you like, or just leave it simple.

Examples: The best way to learn a language, IMO, is by looking at code in that language. Unfortunately, most coders only comment when absolutely necessary, comments are usually made to explain bizarre or unorthodox coding techniques. In this case, the comments would be there specifically to help those who want to learn from these examples.

Do you see what I mean? There could be a CCAEP for java, perl, C, C++, etc. It would be similar to the perl cookbook except searchable (and one for every/any language). It would take a community effort to build something like this, but this would be such a valuable resource if it existed.

I think the 'net really lacks a resource like this.

What do people think? I really don't have much time on my hands, but the more I think about it, the more excited I get.

What do you "oldtimers" (meaning truly experienced coders) think? Is it a worthy endeavor?

------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[kmj]

okay, I really want to do this now. There are so many cool things that can be done. Of course, the "Hello World" could be there; there could be something that goes through all the ASCII stuff and prints it out, so newbies can gain an understanding of ascii. there can be a proggy that deals heavily with string.h, something that opens and closes a tcp/ip connection, one for pointers that creates pointers to const locations (char *const) and pointers to constant data (char const*). So many things, that even experienced people can use as a quick reference. I've written a simple ascii-based Life game that I have at home, maybe I'll do something with that. Someone could do one that deals in SDL (or there could be a bunch of little ones for each SDL function.) blah blah blah, etc. Obviously, the possibilities are limitless.

I don't have much time on my hands, but I think I want to get started working on this tonight, maybe get some simple ones up for C.

------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[JoniMitchellRockedMyWorld]

kmj: sounds like a great idea. I'd love to contribute but I've only recently started to learn C so I'm kinda useless at the moment.

[Dru Lee Parsec]

Go to sourceforge.net and start a project for it. It's a great idea.

[TheLinuxDuck]

kmj:

I emailed you, but did it from work, so I dunno if you got it or not.

I think you knew I'd be interested in this. http://www.linuxnewbie.org/ubb/smile.gif

Email me or something, and we'll get into serious mode, or something funky like dat.

------------------
TheLinuxDuck
Wait... that's a penguin?!?!?

[kmj]

Originally posted by TheLinuxDuck:
kmj:

I emailed you, but did it from work, so I dunno if you got it or not.

I think you knew I'd be interested in this. http://www.linuxnewbie.org/ubb/smile.gif

Email me or something, and we'll get into serious mode, or something funky like dat.


I already replied... http://www.linuxnewbie.org/ubb/biggrin.gif

we should compile a "wishlist" of
a) functionality ...and
b) examples

We'll chat. I'm going to bed. http://www.linuxnewbie.org/ubb/smile.gif



------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[jemfinch]

http://jemfinch.shacknet.nu:81/cgi-bin/bookmarks.pl

All my bookmarks are in a mysql database. I have tools which can add bookmarks on the command line and already have a crude working search made (http://jemfinch.shacknet.nu:81/cgi-bin/bookmark_search.pl ), though not integrated into the bookmarks page (I've been busy for the past few days, and I hate learning HTML).

Anyway, a system like I have for my bookmarks could easily become a catalogue of anotated source code. It's got the hierarchy and the searchability already there -- all it has to do is stop being ugly (and, since I hate html, someone else could do the work to de-uglify it).

It's actually really simple, the product of but a couple hours' work (mostly spent relearning SQL [I hate non-turing complete langauges])

Gimme a shout as to what you think.

EDIT: Of course, different sorting/display methods (alphabetical, etc) would be trivial to implement.

Jeremy


[This message has been edited by jemfinch (edited 22 September 2000).]

[kmj]

Jemfinch, looks cool. Sounds like you're interested.

I know what you mean about html; I'm in the same boat. (check my homepage for proof).

It seems like a SQL database would be the best way to store the files. I don't know if I'll have much time to learn Sql anytime soon, though.

About the search: doesn't html support metatags or something, where you define a list of key words that the document deals with? (any HTML gurus out there?) Perhaps that would be all we need to use. Mainly, I think we'd need something like this, because were we to use a full-content search, anyone who did a search on "printf" would probably receive every single C file there was. I think the author of an example should have control over when these files come up in searches.

For starters, I'm going to look into setting up a sourceforge account, as Dru suggested.

Then, the two most important pieces are building a good set of example code to get started and figuring out how to put it all together (which probably means learning sql.)

------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[jemfinch]

Originally posted by kmj:
About the search: doesn't html support metatags or something, where you define a list of key words that the document deals with? (any HTML gurus out there?) Perhaps that would be all we need to use. Mainly, I think we'd need something like this, because were we to use a full-content search, anyone who did a search on "printf" would probably receive every single C file there was. I think the author of an example should have control over when these files come up in searches.
[quote]

Though the HTML metatags idea is a good one, we can still (quite easily) implement a full text search too (for those who want a little more control over their search). Simply take each term that they search for separately, and keep a running "score" of each file that matches (I developed something like this for a friend of mine's job this summer). Voila, we've got an already ranked full text search ready to output.

If that didn't make any sense, don't worry, I'll get a prototype up sometime.

As a note, if there are any experienced perl/DBI hackers in the crowd, I'm trying to optimize my script a bit (it runs too slow for my tastes right now). I'll be rewriting it in C in a bit to see what the speed difference is too.

[quote]
Then, the two most important pieces are building a good set of example code to get started and figuring out how to put it all together (which probably means learning sql.)


Of course, I have some decent example Perl code http://www.linuxnewbie.org/ubb/smile.gif I also have some C code I could show as examples.

Jeremy

[Sweede]

http://www.weberdev.com and

http://www.cgi-resources.com/
everything you said above.


[This message has been edited by Sweede (edited 22 September 2000).]

[kmj]

True, except these seem to be dealing with web development only. Also, the cgi-resource index doesn't seem to be instructional in any way. I wouldn't want to require any sort of membership in order to access this information.

All the same, it looks like both would make good models.

------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[witman]

Hey, wouldn't it be a great idea to integrate this into an existing programming environment. Even if it was just a help button.

I was thinking more along the lines of the way VB works when you highlight the code and press F1. It would automatically bring up the search using the highlighted text. http://www.linuxnewbie.org/ubb/cool.gif

Let me know what you think.


------------------
The WITMAN Cometh!

[kmj]

So I've been a bit de-winded since something like this has been done before, but I'm still gung-ho.

------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[kmj]

Originally posted by witman:
Hey, wouldn't it be a great idea to integrate this into an existing programming environment. Even if it was just a help button.

I was thinking more along the lines of the way VB works when you highlight the code and press F1. It would automatically bring up the search using the highlighted text. http://www.linuxnewbie.org/ubb/cool.gif

Let me know what you think.




I was thinking along the same lines: VisualStudio supports OLE, and Kdevelop supports macros (or will soon). I'm sure a macro could be inserted into vi. You wouldn't have to keep a local copy of the info, it could run out to the web on command. (Though, we could also make a big downloadable version of the database.)

I guess, though, for things having to do with web development, the smartest thing to do would be direct people to weberdev.com. (maybe. weberdev makes you have an account, and imposes an "EULA" on you, which we may or may not want to do...)



------------------
-Pacotron- You are what you edit- vi -------- GAIM: KMJ2L
Don't be left out! STAND UP AN BE COUNTED! (http://www.cs.rit.edu/~kmj9907/cgi-bin/pollster.cgi)
--*real men use man*--
-The only reason I keep my DOS partition is so I can mount it like the b*tch that it is.

[kmj]

I wanted to mention that the comments don't have to be the overriding point of the programs. They should all be compilable and runnable programs, even if kind of pointless. You don't have to feel like you're writing a book; in fact, I think some people may find that a tremendous amount of comments get in the way of reading the code.(this is somewhere that you can't please all the people all the time, I think) As long as a user can understand what you're doing and why you're doing it.


At this point I realize that I actually responded to the wrong topic (kind of), but that's okay. http://www.linuxnewbie.org/ubb/wink.gif http://www.linuxnewbie.org/ubb/tongue.gif

[TheLinuxDuck]

I was just thinking.. what if we had a link in the html doc to another doc, a 'comment doc' that is solely for explaining a part of the code better.. so, the comments of the source would be general, with some specific's and then have a specific comment from a link.. like, if the programmer was looking up how to use printf.. the code could look something like:


int main(void)
{
/* Simple usage of printf to display a string and an integer -- */

printf("Integer: %d\nString: %s\n,
556,"Test string, man!"); // more on printf
return 0; // more on return
}


Then, the two comments "more on..." (hey! don't call me that!) can actually be url links. The one for printf could go to something like:

printf:

printf and it's derivatives (sprintf, fprintf) all allow many
different types of format identifiers. Integers, strings, floats,
doubles... width specifiers, precision indicators...

To print a string to 30 chars, always, use:
printf("%30s",stringvariable);

To display a float to two decimal places:
printf("%.2f",floatvariable);

Some other uses are:

..
..
..
..

Follow these links for examples of:
using printf to display dollar amounts
fprintf
sprintf
..


Etc.. kinda like a comment, but it's not cluttering up the whole code.. maybe if there was a specific area of the code that the user wanted to focus on, they could click on the keyword, and it would bring up the authors comments..

The more I type this, the qooler it sounds.. maybe we could have hyperlinks for different parts of the code. Like, have different words or comment fields linked to give more detail, or other exmaples, etc..

Too bad there's no easy way to do all this. http://www.linuxnewbie.org/ubb/wink.gif
Am I being clear enough? Sometimes I don't know if I am explaining things clearly or just rambling.. I'm a ramblin duck.

------------------
TheLinuxDuck
Wait... that's a penguin?!?!?
:wq

[This message has been edited by TheLinuxDuck (edited 18 October 2000).]

[kmj]

Definitely seems like a good idea

[TheLinuxDuck]

Originally posted by kmj:
Definitely seems like a good idea

Infamous last words... http://www.linuxnewbie.org/ubb/biggrin.gif

That and "What's this button do?"

------------------
TheLinuxDuck
Wait... that's a penguin?!?!?
:wq

[jemfinch]

Just felt like ressurecting this thread before I do some work on the project.

Some ideas I had that I think I could implement:

1) Of course there should be a hierarchy of examples; probably starting first with the language, then with the subject, then sub-subject, and so on. I've already implemented something like this with my bookmarks, so that would be simple.

2) Given that we have this hierarchy, I think we should be able to link to other examples *from within the code*. IE, in an example about how to parse command line arguments, if we use a printf, I think we should be able to insert a comment something like, "/* c-output-printf */" that could easily be parsed into a link to examples of printf in C.

3) If we plan on having any sort of scaleability, we're obviously going to have to have to have this backed by a database. I'll whip up something once I find out what metadata we plan on storing.

Whelp, that's about it. Let me know.

Jeremy

[billyjoeray]

I think this is a great idea.

The first goal should be to get the design figured out and once you have that you could set up a Wiki server or CVS server or something like that for people to submit to it.



------------------
For-pay Internet distributed processing.
http://www.ProcessTree.com/?sponsor=21568

[7DeadlySins]

post when you get a site set up, and I'll donate as much code as i can. I've done a fair bit wih PThreads and UNIX netowrk sockets.

7DS

[kmj]

Here is the current repository (http://www.geocities.com/bfkester/ccae.html)

We've got a few examples up, and links to a Mission statement and Todo stuff...

[YaRness]

Originally posted by kmj:
Here is the current repository (http://www.geocities.com/bfkester/ccae.html)

We've got a few examples up, and links to a Mission statement and Todo stuff...

i looked at one of those... code with 5 lines of comments between actual lines of code is a bit hard to read... maybe either TLD's idea of having links, or maybe have a short commented version and a long commented version of each code, links in the short version to same place in the long version.... i know for me it's easier to see code as one big thing, and THEN try and pick apart the details. maybe that's just me.

if i start to have some time free, and succeed in building my new box, i might wanna help on this (various programming experience, i can even make really ugly web pages, and i could use some practice doing web scripts/applications anyway). prolly not for a few months at least. but hey, s'not like you have a due date or anything.


------------------
"Assembly of Japanese bicycle require great peace of mind."
Registered Linux User #188285 http://counter.li.org/
------------------

[kmj]

Originally posted by YaRness:
i looked at one of those... code with 5 lines of comments between actual lines of code is a bit hard to read... maybe either TLD's idea of having links, or maybe have a short commented version and a long commented version of each code, links in the short version to same place in the long version.... i know for me it's easier to see code as one big thing, and THEN try and pick apart the details. maybe that's just me.

if i start to have some time free, and succeed in building my new box, i might wanna help on this (various programming experience, i can even make really ugly web pages, and i could use some practice doing web scripts/applications anyway). prolly not for a few months at least. but hey, s'not like you have a due date or anything.




Yeah; we really haven't decided upon any strict definition of how the examples should be. For some, the comments may be what they're more interested in; other just want to see the code, and skip the comments. It's hard to say. The examples vary widely in how much they're commented. Some were written with the obvious purpose of explaining something specific, while others were added because they were goods examples of how to implement some simple task. Right now the only thing that I ask is that it's readable (not obscured), somewhat pretty (use common indenting styles, etc.), and actually does what it says it does. http://www.linuxnewbie.org/ubb/smile.gif I do like the idea of the links; we're gonna have to put this whole thing together soon, and decide how we want it to be.

Thanks for any help; things are going slowly at the moment because LD and I have both been busy; hopefully, I'll be able to spend alot more time concentrating on this after thanksgiving.

[TetsuoII]

Great idea. Great page.
I like the sourcecode layout and the commenting style. After dec. 7th I will take some time and write some C/C++ code if you want to.

The main-page should be divided into categories, but that is a problem that I guess will be solved when the number of sourcecodes increases.

Thanks,
T.