RANT: Throwing around code does not REALLY help users.

[quok]

I have long thought that throwing "working" code at a user in an attempt to help them was indeed not helping anyone at all. I think that it generally does a lot more harm than good. Let's take this post for example.

User A has some code that was gifted by User B. It works in one scenario, but not another scenario that User A thinks is valid. User A then makes a post asking why this gifted "working" code does not work for this scenario. Clearly, User A does not understand what the gifted code actually does and does not do. Is this a failing of User A, User B, or the code? Ultimately, I'd say that all three are are fault. Let me explain why.

1) We do not know if the code posted by User A was modified in any way, and User A doesn't give very much context about how the code is used either, aside from how some devices are set up in a virtual machine. The code in question may or may not be at fault here. It could be very possible that this code is being incorrectly called from elsewhere.

2) User A doesn't explain what debugging (if any) has been attempted so far, and what the results of that debugging were.

3) User B responds only with "you cannot use that code for this purpose. Use this other code instead." This is compounding the problem! I now fully expect User A to make a post saying "When I use the new code, the situation I had before is reversed! Device A no longer works, but Device B does!" User B makes no attempt at all to explain WHY the first code does not work as expected, or how the newly posted code is supposed to work. It is not explained if the one replaces the other, or if both pieces of code work together somehow.

We don't know if User A understands either bits of gifted code, or the underlying devices in question. Has the wiki been searched? Have the appropriate specs been read? While the general quality of those posts themselves are quite lacking, throwing code at User A certainly isn't helping to address the underlying problem: a lack of knowledge. User A isn't really helped here at all, nor is anyone else that may have a problem with User B's code in the future, should they also be inappropriately "helped" by this selfish code slinging going around. This entire thread really shouldn't even exist; User A would have been just as well served by User B if the entire thing had happened via PM, and then we wouldn't have other users reading the thread hoping for help but only being let down in the end.

Now let's take a look at another example thread.

Here the OP has a problem, and it appears that the OP has tried some debugging. The OP points out the wiki article on the subject has been read as well as some other resources, but the problems persists and so the OP would like some advice. The thread goes along reasonably well with comments and suggestions, and it appears the OP is making progress toward solving the problem.

But suddenly, there's once again a bunch of code thrown at the OP with no explanation other than "it follows the intel controller pdf." I'm wondering, which intel controller pdf? Intel has many controller datasheets available, a link to the pdf that is followed by the code would be nice. Granted, that link (or even the PDF itself) may be in the zip file that is linked to, but perhaps I'm not interested in downloading someone else's code on the off chance that it contains a datasheet that may or may not have been referenced yet. And I will point out the OP specifically asked for SUGGESTIONS, and NOT code. I'll give 5 cookies to the OP just for that. The OP is trying to learn and figure things out based on the advice of others, not their code. That is the type of positive reinforced learning that will help the OP down the road. It seems to me that the person posting the code isn't really out to help anyone at all, but rather is entirely self-serving and just looking to stroke their own ego, or have others stroke it for them. I personally do not think this is the sort of user that we need around here.

So what can we do about this? Just stop posting code entirely? Well, no. There are times when posting code may indeed be the correct solution, but quite often the largest problem there is finding the correct code to post.

Sadly, some people really do need to look at other people's code to learn. To those people, I'd like to suggest they either find another hobby, leaving OS Development (and programming in general) far far behind. But if you must continue with this hobby, then it's time to find another path. There will come a time, when you get far enough in your OS development endeavors, that tutorials and code samples become sparse. Datasheets may or may not exist. Your device may be supported by Linux, but perhaps you don't want to reference that code because it makes your eyes bleed, or because you cannot base your code for your proprietary OS project on GPL'd code. If you must refer to existing code now to write your code and get it working correctly, you really, really, really need to work on fixing that. Put your project on hold, learn to become a better programmer somehow (books, schooling, published papers, perhaps even find an Ancient Knowledge Repository and have it all downloaded into your head, but beware, there's no Asgard around to help save you later), and come back to it later. Or spend many painful eye-watering hair-pulling hours trying to figure it out for yourself, or through the advice and suggestions of others. Eventually you'll learn enough and all the proper brain connections will be made that you'll be able to apply past experience to your current situation.

For anyone that is responding to a thread and is thinking of posting some code, DON'T DO IT! Instead, perhaps suggest a wiki article, datasheet, a google search with keywords, or maybe even a tutorial. Oh, a wiki article doesn't exist for this subject? Then spend some time and create one. Does a wiki article exist, but it doesn't cover this problem, or is very hard to follow? Again, spend some time on the article. Clean it up, add missing bits of information. The wiki is for everyone, and is always going to be a work in progress. Many many more people will be helped by a good wiki article (complete with references to datasheets, publications, and/or other online resources) than will be helped by your super-awesome leet and maybe or maybe not bug ridden and semi-commented asm code that most likely doesn't have any kind of license on it (which then legally prevents anyone from doing anything with that code anyway).

In the above two referenced threads, a moderator could go delete the "here, use this code" posts, and nothing at all would change. Arguably, the OP in either case would be better off if those posts were deleted.

The forums are a great resource. There's many helpful people here, and a great many valuable threads full of very very good information. The best threads don't have complete code attached to them, either. There may be snippets here and there, but most of them either don't have any code at all, or certainly don't have complete working drop-in code.

In many cases, I view the forum as a place to say "Hey, the wiki is lacking this information. I don't have the knowledge to write an article about this, but someone here does. Would you mind writing something in the wiki?". There are many forum posts full of information that should be added to the wiki, but the relevant articles haven't been updated (or even created). We're all guilty of this, even me. If a forum post points out a shortcoming in a wiki article, it is more appropriate to update that wiki article with the correct relevant information than to continue on educating the OP in a forum thread. Or perhaps do both. If you know some information, but not all, ask in the forums if you are correct, and then go update the wiki. Not all forum posts are relevant for the wiki, but many contain detailed information about specific problems that should at least be linked to from the wiki.

I really think the focus of the forum should be community related. It is a great place to meet new people with similar interests, find someone to test your latest OS release (or perhaps even contribute to it), and get feedback that helps you grow as a programmer, advancing your knowledge and experience in the field. In my opinion, the best way to stroke your ego (if you really want to do that) isn't by throwing code around, but by helping others become the expert programmer that we all want to be. This will not only help them to accomplish their own OS related goals, but may also help them to build confidence and learn new techniques that are valuable in other areas of life outside of programming and OS development. (Yes, such areas really do exist!)

You may be thinking "many wiki articles contain code, how is that any different?". It is true, there's many wiki articles full of code. Some contain code snippets, and some contain full working examples. The wiki is a much more appropriate place for long-living code samples. It's often quite good to explain the theory behind a concept and then give some code samples (or pseudocode) that illustrate what was just discussed. That is how professional papers are written. If you read Jeff Bonwick's 1994 paper on the Slab Allocator, you will not find a complete working implementation of the slab allocator, but you will see code listings when they are appropriate to illustrate a point or concept that was just discussed.

I did not intend to call anyone out with this little rant of mine. I tried to use generalities and say things like OP, User A and User B instead of the actual users involved so that the points I was trying to make could be applied to a wider variety of situations than the threads I linked to.

[piranha]

I do agree with you quok, using code that other just give out is a problem. A lot of us use old code for our own stuff, hell, I'm also guilty of this.

I believe that there is a middle ground. Either saying "Here, use this code" or "hey, you must write it yourself" isn't totally fair. I think that if someone were to say "use this code as an example", and the OP did that to learn, that would be fine. However, it's unlikely that that would happen, most people are more likely to just take the code and use it without trying to understand.

I think that as long as you plan on rewriting the code later, and you just want some quick-and-dirty code to use, thats OK. But many people aren't doing that, they just want code so they don't have to learn, due to pure laziness. I, for example, have a borrowed printf from an early Linux, and some hard drive RW code that I have also borrowed. While I have no modified the printf (since it works well), I have only used the HDD RW functions that r/w one sector at a time. I have written all the other usage functions that interface with the borrowed code. I have also based a lot of my VFS off of an early Linux, and my MM and tasking system in my kernel are heavily based off of JamesM's tutorials.

I see nothing wrong with my above actions, because A) I don't want to write my own printf, because I know that I could and it would be pointless. B) The HDD RW code is about 20 lines long, and thats it. C) I did write it myself and D) That code is the code that I am currently working on rewriting in my own style (as I planned when I first used it).

So, there is a middle ground, as long as its small, pointless to write yourself, or plan to rewrite it it's alright. However, this is not easy to keep track of and not many people are going to follow these rules. Which is why I agree, quok, that people need to stop handing out code, with the exception of utility functions.

The other major problem (I agree) is people taking code and not learning about it. If you don't learn about the code, you wont be successful in using it. This is important: if you aren't willing to learn, leave because you will NOT make it.

I mean really, come on. Put some effort into the hobby you chose.

thank you quok!

-JL

[gravaera]

Sadly, some people really do need to look at other people's code to learn. To those people, I'd like to suggest they either find another hobby, leaving OS Development (and programming in general) far far behind. But if you must continue with this hobby, then it's time to find another path. There will come a time, when you get far enough in your OS development endeavors, that tutorials and code samples become sparse. Datasheets may or may not exist. Your device may be supported by Linux, but perhaps you don't want to reference that code because it makes your eyes bleed, or because you cannot base your code for your proprietary OS project on GPL'd code. If you must refer to existing code now to write your code and get it working correctly, you really, really, really need to work on fixing that. Put your project on hold, learn to become a better programmer somehow (books, schooling, published papers, perhaps even find an Ancient Knowledge Repository and have it all downloaded into your head, but beware, there's no Asgard around to help save you later), and come back to it later. Or spend many painful eye-watering hair-pulling hours trying to figure it out for yourself, or through the advice and suggestions of others. Eventually you'll learn enough and all the proper brain connections will be made that you'll be able to apply past experience to your current situation.

I humbly agree...

In the above two referenced threads, a moderator could go delete the "here, use this code" posts, and nothing at all would change. Arguably, the OP in either case would be better off if those posts were deleted.

Or if he demonstrated that he was truly fit to do OSDev, and downloaded the relevant documentation and wrote out a mini-spec like every other serious minded OSDev enthusiast. Then, taking the fruit of his reading, he would write his own code. This would present the obvious idea that "If this code is fully self written, from a specification, then I already have all the info in my head. If there's a bug, there's nothing anyone on the forum can do that I can't."

That will foster an attitude of self-dependence.

Personally, I think the way that someone like NickJohnson uses the forums is probably the best; He doesn't much post implementation details. I always see him coming up with a theory filled post with well-thought-out ramifications that usually makes for a good read. A good few times, his posts have geared me to realize that there's stuff in there that I don't understand, and has prompted me to go read up the subject. A truly exemplary member, if you ask me.

I keep a saying in mind: "Small minds discuss people and things. Average minds discuss events and possibly politics. Great minds debate ideas.". I personally don't see why people who want to do OSDev seem to think that demonstrating a lack of a deep mind will help in any way.

More specifically, he is already good at his programming language, and he has come to the realization that honestly, the most people on the forum can do with your code is suggest X, Y or Z, and in the end you'll have to fix your own problem, unless it was obvious enough to have been seen by another user...in which case it becomes a violation of the rule that a programmer who is undertaking OSDev is expected to be good at debugging.

The real gold mine about the forums, as far as I can see is not the 'online help' that some users seem to become hooked on, but the mere presence of great minds to discuss the advantages and disadvantages of theory.

And honestly: how many times will newcomers post the basics?

"Grub gives me error 13" {Solution: Until you're good enough to venture away from the recommended option, which is ELF, stick to it, and read the LD manuals};
"I can't get James Molloy's code to compile" {Solution: Stop trying to compiler other people's code.};
"Help with paging" {Solution: Paging is explained in depth in the Intel Manuals. The forum rules state you should have read the intel manuals. This question indicates that you have not read the intel manuals. Please read the intel manuals.};
"I don't understand how to implement a stack based memory manager" {Solution: you're a newbie. Use a bitmap.};
"Any other basic problem" {Solution: as a general rule, operating system development in itself is like a self-imposing barrier to block out people who aren't fit for it; Do you find yourself unable to surmount the simplest hurdles? Maybe you're one of the those who are meant to be expunged.}

--Interesting read
gravaera

[quok]

I do agree with you quok, using code that other just give out is a problem. A lot of us use old code for our own stuff, hell, I'm also guilty of this.

I use lots of my old code all the time. I'm constantly porting code from previous kernels to my current project, fixing it and updating it where needed. There's nothing at all wrong with this. I've also taken code from OpenBSD and imported it to my project. I know how to use strlcpy, I know how it works, and I don't feel like writing it myself. The implementation of that function isn't important to me, so why not reuse the code?

I believe that there is a middle ground. Either saying "Here, use this code" or "hey, you must write it yourself" isn't totally fair. I think that if someone were to say "use this code as an example", and the OP did that to learn, that would be fine.

I hope I didn't come across as saying I advocate "hey, you must write it yourself" because that is not at all the point I was trying to make. One of the big advantages of open source is code reuse, after all. But if all you do it reuse someone's code because you can't get your code to work, you aren't solving the underlying problem, and you really aren't helping yourself. If you can't get your code to work, chances are you don't understand why the other code does work. That is a situation that needs to be fixed.

But I agree there is a middle ground, and I said it in my rant: use the wiki. Give everyone the tools they need to succeed. Those that are attempting OSDev that are unwilling to learn quickly fail and go away, never to be seen again. There's example after example of that in these very forums.

I think that as long as you plan on rewriting the code later, and you just want some quick-and-dirty code to use, thats OK. But many people aren't doing that, they just want code so they don't have to learn, due to pure laziness.

I think most people that want code aren't doing it out of laziness. I think they are doing it because they don't think they can write it themselves. Either it's a lack of knowledge, or a lack of confidence. Both of those can be fixed, it just takes time. I speak from experience here.

I've got 15 years experience programming under my belt. For the last 8 or 9 years, I've felt that I've got a fairly good handle on programming and can tackle anything. I first attempted to write a kernel back in 2000 or 2001. I thought I'd be able to accomplish it, that it wasn't anything terribly out of my league. Boy was I wrong. I was borrowing, stealing, and referencing code left and right. I eventually got something that was self hosted and relatively stable. But I didn't understand 90% of the code. It was both a lack of knowledge and a lack of confidence. I'd look at datasheets and my eyes would gloss over. I knew all kinds of programming theory and was making very good money as an application programmer, where I was quite well respected.

OSDev is a different world entirely. I didn't have any problems with application programming because I was doing it for years, and I had confidence in my abilities. It took a lot of late nights and hair pulling to build up that same confidence in myself when it came to OSDev. But I'll tell you this: nothing has felt better, and I'm very glad I did it that way. It took a lot of time, and I've had many different kernels since then that had at least the same amount of features. But I understood the code, I wrote it all, and it was all mine.

I may have lost sleep and hair in the process, but the knowledge and confidence has stayed with me and improved OTHER areas of my life as a result. I no longer fear datasheets, cpu manuals, or asm code. Hell, the confidence I gained in myself by figuring all that out helped when it came to dating, too. I figured "If I can write an ATA driver, I can ask this cute girl out without fear of rejection. If she does reject me, oh well, more time to work on my OS." Ironically, now I'm married and have 2 kids, and so have even less time for OS development. Or perhaps that is not ironic at all.

It's just my experience, and I hope that by laying out where I started and how I came to where I am today, it'll inspire others to take the time to "do things right."

[01000101]

Quok, that was pure gold. Passing out source code will never truly fix the problem. Even if the code works exactly as the OP wanted, there's still a fatal flaw, no knowledge was actually gained. The problem wasn't really addressed, it was swept under the rug. As soon as the OP needs to fix a bug, modify, or port the gifted code, they will probably need to ask for help again as they will have no idea what it is *actually* doing.

The wiki needs to be the primary focus of this entire website, imo. Everything useful from the forums should be there and if it's not and someone needs help, the person who *does* know the answer would do worlds of good to update/create a wiki article that contains the answer and link to it in the thread .

Btw, excellent Stargate reference.

[dosfan]

Sticking my neck out here..

I'd agree if the example threads didn't point the finger at Dex. What is everyone's problem with Dex on these boards?

[Combuster]

I'd agree if the example threads didn't point the finger at Dex. What is everyone's problem with Dex on these boards?

Short version: for consistently ruining attempts to enforce some of the mentioned self-sufficiency (which usually also are violations of forum rules), and being unable to handle confrontations or criticism.

[quok]

Sticking my neck out here..

I'd agree if the example threads didn't point the finger at Dex. What is everyone's problem with Dex on these boards?

Did you read the last paragraph of the rant? I didn't mean to call anyone (even Dex) out. There's plenty of threads where other people do the exact same thing. The only reason I used the two threads I did is because they're the latest examples of code being thrown around in an attempt to help.

[Brynet-Inc]

Whoo! Stargate references!

I wholeheartedly agree with quok on this one, quite a few people here (..hi Dex) are posting complete implementations without even taking the time explain how it works or what it does.

"Oh hai! he'res mah c00de.. i't'li fix that."

That's not very productive, in the long run it's not going to help them.

[bewing]

I'm going to partially disagree with quok. There are circumstances, and then there are other curcumstances.

For example: I am currently working on floppy controller code, and it is very confusing, because the old wiki article was a stub, none of the emulators match any real hardware that I can access, the datasheet contradicts itself in many places, and leaves out several vital pieces of info.

Honestly, I'd LOVE for someone to throw me some code for floppy controllers at this point, that works on all real hardware.
I can learn from code just fine.
I can try each little subsection that is different from what I'm doing now, and see what they did that makes it work.
That is EXTREMELY useful information.
But for newbies, you are right, quok.
It takes a hell of a lot of experience to be able to take apart a piece of working code, to see WHY it works. Really, just as much experience as it takes to read through somebody else's code, to tell them why theirs DOESN'T work.

So you have to target your audience. If it is a newbie posting, tell them in words how to do it, or pseudocode. If you are talking to an advanced OSdever -- feel free to post code, I'd say.

[Solar]

My impression, not even (only) gathered on this forum, is that some programmers - among them pretty competent ones - cannot read/write technical documentation to save their lives.

This is usually mixed with the mistaken concept that "my code is so well-written it doesn't need docs" / "I can learn best from reading source", and a leet attitude of looking down on those who consider technical documentation to be useful / necessary.

PS: This is not aimed at the posters from the threads linked, or the previous poster, but merely a general observation.

[Combuster]

Everything should be done in moderation. A good programmer must be able to do it all - Write from specification, write a specification, write documentation, and draw conclusions from existing code (read: debugging). People who are good at debugging get a +2 synergy bonus at reverse engineering other people's code. Most newbies (and paid programmers alike!) however lack the ranks in that skill, and can consequently only use other people's code as a black box. And consequently, need to ask "their" *cough* party's wizard to rewrite the draconic runes. Which in real life would cost you a number of dollars.

Second observation, people who really are able to draw conclusions from other people's code, are usually skilled enough in other areas te be able to find the relevant code in question - If I can't find proper documentation on graphics card X (which is quite often), the next thing I do is grab the relevant x.org sources and tear it apart, symbol by symbol. It is hard work, but success can be rewarding.

So even for the guru's, I wouldn't want to post code - if they need it, they should be able to find whatever is relevant on their own. And otherwise they would have read "how to ask smart questions" well enough to formulate a proper looking-for-code-references question.
Interestingly, I don't recall bewing for actually asking that question he just mentioned - go draw your conclusions.

[AJ]

Hi,

Very nice post quok - I can't find the old one, but if you don't have a blog any more, you need one

Cheers,
Adam

[jal]

Although I agree with the general sentiment here, I disagree with the opinion that you must understand code to apply it. The only thing you need is to know its behaviour, its interface specifications. Who of you really knows, and has studied, code from the libraries he has linked (outside OS development)? I certainly haven't. Although I admit having looked into its sources, I havent studied SDL extensively, for example, I'm more than happy to write SDL_UpdateRect() without thinking twice. And to stay with OS developement, how many of you with a POSIX-based OS haven't taken a Linux driver and ported it to their OS, without reading the accompanying data sheets (provided they were available)? And what about reverse-engineering reverse-engineered 3D-drivers (you know who you are)?

The problem is that people that ask questions about code that was posted don't understand programming itself. Posting code will feed them, make them believe they're all powerful with their new l33t m4ster sk1llz, but as soon as they hit a bump (e.g. they did not even read the comments in the code, or failed to understand the interface), they start asking questions in a very unsmart way (or even be rude, "hey, you gave me this code, it doesn't work! fix it!"). So, let's all agree that handing out code to aspiring but unfit OS-developers is bad, but let's not pretend to be holier than the pope, now shall we?


JAL

[Solar]

There's a difference between a function library, complete with test cases, documentation, a CHANGES.txt and an URL being given where to retrieve future maintenance releases, and an undocumented piece of code tossed at someone.