A Guest Post

Published March 16, 2006
Advertisement
The following post is presented to you courtesy of Promit. Feel free to rate him down or up accordingly!

I definitely agree with Washu that tutorials are kind of a dangerous fad that harm the learning process. As usual, though, there is even worse. One particular breed of tutorial is so vile, so addictive, and so deceptively simple that it poses a real threat to beginners everywhere. That threat is the source code tutorial. Usually these tutorials are comprised largely of code, with every line commented whether it needs to be or not, and they have little or nothing of substance.

So, what makes source code tutorials so bad? Obviously they get copy-pasted into beginners' code bases frequently, but that's not the only reason they're problematic. They detract from the subject at hand, which is the concept that is supposed to be conveyed to the reader. The focus is shifted away from understanding what is going on and why. Meticulous attention (in the form of a comment or several) is paid to silly things, like why a variable is declared the way it is, and the bigger picture is lost in a sea of implementation details. The code and the concepts are combined in a tangled mess, and the accompanying comments by their very nature are vague and ultimately useless. Worse still, code instills a feeling of a single Right Way to do things. While it's certainly a comfortable position for a beginner, it's not a good one, and the problem is exacerbated by the fact that most tutorial code is pretty badly written to begin with.

Consider this very short, simple snippet from a certain well known OpenGL tutorial site:
glGenTextures(1, &texture[0]);// Create The Texture
// Typical Texture Generation Using Data From The Bitmap
glBindTexture(GL_TEXTURE_2D, texture[0]);
Two short lines of code, which form the fundamental basis of texturing in OpenGL. Yet the comments are utter trash, and the code itself conveys no useful information to a beginner. What is "Create The Texture" supposed to mean? Does it load data from disk? Does it allocate space in graphics memory? Does it send data to the video card? In fact, it does none of those things. The second comment carries a lot of similar implications, all of which are also completely wrong. It doesn't even begin to suggest that it sets the value of a particular state in the internal OpenGL state machine, which is what the second function call actually does.

What a lot of beginning and intermediate programmers fail to realize is that code is not a medium for conveying ideas. Code is little more than a crude tool for making the computer do what we want. We use comments to keep ourselves sane in the process, but you can't use line by line comments to explain how a system works. The scope is too narrow, and most of the details are irrelevant to the question at hand. Well written code is usually obvious to anyone reading as long as they are familiar with the algorithms, data structures, and other concepts involved. (Often, even familiarity with the programming language in question isn't needed.) A tutorial should focus on explaining those concepts, preferably without any code whatsoever. If someone truly understands what the tutorial is trying to teach, they won't need any code in order to write it on their own.
0 likes 21 comments

Comments

jollyjeffers
I see, and for the most part agree, with Promit's point.

What do you think of things like the DirectX SDK samples? They all come with a "whitepaper" explaining what the general idea/concept/method is, but for the most part they are source code "tutorials" (I see it as a minor thing to argue between calling it a "tutorial", "sample" or "example")...

I quite like them (as well as other open-source graphics/technology demos) as PART of my learning toolkit [smile]

Jack
March 16, 2006 10:11 AM
meh
Tutorials are useful but most 'Tutorials' don't really fit the scope of what they should convey.

In my mind a tutorial should show you how to accomplish something in a in-depth step by step way with a modicum of explanation. They should be aimed at people who know what they are doing and are looking to get up to speed in a new environment.

It's a complete naive way to learn if you are a beginner and most seem to be written by people whose skill-set is only just above the level they are writing at. I was guilty of this when I started programming, although I hope I was slightly better than average. Here's an example. The formatting was originally a lot nicer as it started off as a forum posting. That aside its still pretty crappy.

However it was written before I had any formal programming education.
March 16, 2006 10:44 AM
Walley
And the sad truth is the fact that 99% of beginners rely heavily on tutorials anyway. I suppose the under developed self learning skills this group tend to have is a big part of the cause.
March 16, 2006 01:02 PM
superpig
I disagree with your assertion that code is not a medium for conveying ideas. Good, well-written code - sometimes referred to as "self-documenting" code - will convey to the reader a lot of information ("ideas", whatever) about the what the code does and the way it works. Comments are usually necessary to clarify extra parts of ideas that the code doesn't communicate.

That said, I will agree with the notion that code is not the best medium for conveying ideas. It's difficult to convey high-level ideas in low-level code and vice versa. Code is naturally step-by-step low-level stuff which is why comments are usually present to clarify the big picture (high-level) stuff.
March 16, 2006 01:13 PM
Cypher19
Quote:I see, and for the most part agree, with Promit's point.

What do you think of things like the DirectX SDK samples? They all come with a "whitepaper" explaining what the general idea/concept/method is, but for the most part they are source code "tutorials" (I see it as a minor thing to argue between calling it a "tutorial", "sample" or "example")...

I quite like them (as well as other open-source graphics/technology demos) as PART of my learning toolkit

Jack


The DXSDK content I actually find quite useful. I honestly do NOT understand where poeple are coming from with this argument that "oh, the samples are too thick and muddled and there's so much extra fluff". I dunno about them, but when I was learning 3D graphics, and how everything fits together, I cannot remember looking at more than a handful of tutorials (mainly to look at a couple techniques that the SDK did not directly address, e.g. jollyjeffer's shadow volumes article), let alone buy some thick-ass 400-page book. The SDK content, including the tutorials, samples, and documentation file, are great in my opinion.

Oh, and obviously due to my fairly mild amount of experience with tutorials, I cannot comment on much of Promit's ideas, but if Nehe's tutorials really do have code like that...then I'm glad I never went there.
March 16, 2006 01:49 PM
Promit
Quote:What do you think of things like the DirectX SDK samples? They all come with a "whitepaper" explaining what the general idea/concept/method is, but for the most part they are source code "tutorials" (I see it as a minor thing to argue between calling it a "tutorial", "sample" or "example")...
Some of the D3D tutorials, particularly the early beginner ones, are definitely guilty of this. They're partly redeemed by the fact that the comments are generally not one-liners but longer descriptions, but that's not really good enough. Some of the samples are better than others. Tutorial 5 (Texture Mapping) is pure code, and the accompanying text is really very terse. CubeMapGS, however, shows no code except for the shaders, and since it's an introduction to GS, that's probably appropriate. Similarly, ShadowMap has no code at all in the whitepaper, and ShadowVolume's paper is excellently written.

I suspect that the reason D3D's samples are divided like this is that they treat the experienced and beginning developers differently. It's assumed that the experienced developer can do the code for himself, whereas the beginner needs guidance. While it's true that the beginner needs to be shown a lot of the code, that can be done towards the end of the sample, or even in a separate file. Most of the D3D tutorials are reasonably light on source code in the whitepaper; they're just also much too light on explanation.

I think tutorials in general are obsessed with getting the reader tangible results as soon as possible, and source code tutorials merely stand as the worst offenders. This emphasis needs to be dropped (D3D SDK tutorials included), and a little time taken to clarify what is going on without having the code in the way.
March 16, 2006 01:50 PM
MustEatYemen
Now I feel compelled to to create quality tutorials to play the devil's advocate.

Tutorials in and of themselves are aids to learning. Tutorials can suck, Teachers can suck, and Documentation can suck. We can't make a blatent statement that because the majority tutorials are written by people looking to further their name and as such are cobeled together to look nice w/ a hyperlink attached to a resume.

Tutorials can be informative and help to further the understanding of the underlying system. Where documentation may tell you what the system is capable of, a tutorial can give you a look at a way of going about solving a problem.

Meh, it's semantics I see. Something is either crap or not crap, but a category of aids isn't crap as a broad statement. Besides why should Tutorials be crap, while Articles or Books aren't?
March 16, 2006 03:17 PM
Pipo DeClown
I have to agree too, but not with the theory, but with how some sites have managed to produce crappy learning methods like Nehe and GameTutorials.

In theory though, any well-planned set of (code)tutorials should be able to bring information to the reader. And by well-planned, I mean planning all the details from the articletitles to the headings, from comments to functionnames.
March 16, 2006 03:36 PM
MustEatYemen
Time to rank tutorials based on user feedback?
March 16, 2006 03:45 PM
Cypher19
MEY: But how could most users of tutorials be able to give a good ranking? Typically, the incompetent don't realize that they ARE, and a lot of newbies could end up giving an article high points because they got from point A to point B quickly by copying and pasting source code, not because they genuinely learned a lot from the article.
March 16, 2006 08:02 PM
MustEatYemen
hmmm very true.
don't really have a solutiont to that besdies editorial review, and we all know how well that works for science journals. :(
March 16, 2006 08:35 PM
Oluseyi
The solution lies more with tutorial authors than with tutorial readers. Simply put authors need to write better tutorials. Readers, in return, should reject poor tutorials - except that they're usually too inexperienced to tell good from bad.

If "good" tutorials were written and became more common, though, then newer authors would be influenced by the positive practices. So perhaps the onus is on those of us who despise current tutorials to write better ones...
March 17, 2006 04:51 PM
Pipo DeClown
Those who can, write books. Those who can't write books, write tutorials. Those who can't write anything at all, write on the internet.

:S huh?? Don't get it..
March 23, 2006 02:26 AM
Emmanuel Deloget
Quote:The solution lies more with tutorial authors than with tutorial readers. Simply put authors need to write better tutorials. Readers, in return, should reject poor tutorials - except that they're usually too inexperienced to tell good from bad.

If "good" tutorials were written and became more common, though, then newer authors would be influenced by the positive practices. So perhaps the onus is on those of us who despise current tutorials to write better ones...


One part of the problem is not solved: most of the time, unexperienced readers that finally learn something using a trillion tutorials begin to think that since no tutorial was good enough for them, they should write their own one. The problem lies in the fact that sometimes, the tutorials they read and didn't understand was good enough, but their mind were not prepared to the correct solution (a tutorial about using auto_ptr<> can be very fun to read, but unless you understand the fine standard points about destructors of incomplete types (which are turned into trivial inline destructors), you won't be able to correctly use auto_ptr<>).

If you put better tutorial online, they'll only learn faster - thus they'll write their tutorial faster ;) It doesn't mean that their tutorial quality will improve :)

Regards,

-- Emmanuel D.
March 23, 2006 10:00 AM
Lazy Foo
Considering my tutorial site is a code tutorial site I'm going to be biased.

But this is crap. The problem with tutorials is either:
1) They chuck a bunch of theory at user that has nothing they can relate to.
2) They spew too much information at the user at once.

The model for my website is "Show them how to do what they want to do."

On my site, surface blitting is tutorial 2 and pixel manipulation is tutorial 29 (second to last). The reason is to the beginner, pixels mean nothing. But surfaces are just images so they can relate to and comprehend that. By the time they reach tutorial 29 they've become comfortable with surface and are ready to play with them.

The key to teaching is to give them something they can relate to and have experienced. The human thought is based on association.

Quote:Consider this very short, simple snippet from a certain well known OpenGL tutorial site:
glGenTextures(1, &texture[0]);// Create The Texture
// Typical Texture Generation Using Data From The Bitmap
glBindTexture(GL_TEXTURE_2D, texture[0]);
Two short lines of code, which form the fundamental basis of texturing in OpenGL. Yet the comments are utter trash, and the code itself conveys no useful information to a beginner. What is "Create The Texture" supposed to mean? Does it load data from disk? Does it allocate space in graphics memory? Does it send data to the video card? In fact, it does none of those things. The second comment carries a lot of similar implications, all of which are also completely wrong. It doesn't even begin to suggest that it sets the value of a particular state in the internal OpenGL state machine, which is what the second function call actually does.


As a beginning OpenGL programmer I can tell you this: I don't give a shit. I just want to get my image on the screen. I don't need to know how OpenGL works. I will eventually learn how everything works but if you tell me now I have nothing to relate it to and everything will go over my head. I'm going to continue C/Ping code from nehe and playing with it that because I (and most people) learn from experience. I'll learn what's under hood once I need to. By then I'll heve experience with OpenGL and everything won't be foriegn to me.

I will agree that too many just play frankenstein with tutorial source code. A lot of the time they don't even read the tutorials that explain the source. I have an e-mail box full of examples. Fortunately this is temporary because eventually to make thier game they'll run out of code to C/P. Any handicap source tutorials give is short lived because they'll eventually have to learn how things work. They'll be better off than those who just dived into theory because they've already had experience with it.
March 24, 2006 01:12 AM
Extrarius
Quote:Original post by Cypher19
MEY: But how could most users of tutorials be able to give a good ranking? Typically, the incompetent don't realize that they ARE, and a lot of newbies could end up giving an article high points because they got from point A to point B quickly by copying and pasting source code, not because they genuinely learned a lot from the article.
This is exactly the problem I have with Amazon's rating system. I've found that it's most helpful to examine the comments of raters that gave less than 50% rating - if those comments are well structured and make complaints about aspects important to me, it's almost certain that the book is not suitable for my purposes. On the other hand, if they're ravings complaining that the book doesn't do everything, it's likely a decent book that covers the topic well.

Quote:Original post by Lazy Foo
[...]As a beginning OpenGL programmer I can tell you this: I don't give a shit. I just want to get my image on the screen. I don't need to know how OpenGL works. I will eventually learn how everything works but if you tell me now I have nothing to relate it to and everything will go over my head. I'm going to continue C/Ping code from nehe and playing with it that because I (and most people) learn from experience. I'll learn what's under hood once I need to. By then I'll heve experience with OpenGL and everything won't be foriegn to me.[...]
(emphasis mine)
How can you say you'll have experience with OpenGL then, when all you've done is copy and paste code? Experience is the best teacher, but experience involves "getting your hands dirty", meaning that you have to actually try to do something until you acomplish it. If all you've done is copy and paste, you'll see pretty pictures but won't have any idea how things work or why, or how you could solve similar problems. You'll lack the ability to generalize, and after you finish wasting time getting somebody else's pretty pictures to show up, you'll still have to put in the same amount of "hard labor" to have any understanding or experience.
April 03, 2006 02:25 PM
SaurabhTorne
Washu Promit I agree to No comments! hehe :)
Well I realised after reading it that comments are not really reqired. I myself have a habit of leaving long lousy comments.But I am going to change. Specially if the code is not working right then all you can do is comment on it hehe :) They are some sort of stress relief
If we have nicely named functions and variables then comments are really not nessary. I havent done any tuts yet but its also applicable to general programming.
Thankyou
April 04, 2006 11:21 AM
Lazy Foo
Quote:Original post by Extrarius
How can you say you'll have experience with OpenGL then, when all you've done is copy and paste code? Experience is the best teacher, but experience involves "getting your hands dirty", meaning that you have to actually try to do something until you acomplish it. If all you've done is copy and paste, you'll see pretty pictures but won't have any idea how things work or why, or how you could solve similar problems. You'll lack the ability to generalize, and after you finish wasting time getting somebody else's pretty pictures to show up, you'll still have to put in the same amount of "hard labor" to have any understanding or experience.


Quote:Original post by Lazy Foo
I'm going to continue C/Ping code from nehe and playing with it that because I (and most people) learn from experience.
April 04, 2006 04:33 PM
KittyRa
Quote:Original post by WashuYet the comments are utter trash, and the code itself conveys no useful information to a beginner. What is "Create The Texture" supposed to mean? Does it load data from disk? Does it allocate space in graphics memory? Does it send data to the video card? In fact, it does none of those things. The second comment carries a lot of similar implications, all of which are also completely wrong. It doesn't even begin to suggest that it sets the value of a particular state in the internal OpenGL state machine, which is what the second function call actually does.
Haha. My comments are usually just like that.[smile]

July 20, 2006 12:34 PM
algumacoisaqualquer
Well, while I completely agree with this post, there is something I would like to add:

All I learned of OpenGL came from NeHe and GameTutorials - I'm extreamly thankful for them.
It was until my last project, where I had a divided screen showing two cars (player 1 and 2) in a racing game. The game would show things like laps and the car speed on the screen, load the tracks from a file (actually, a lua script!), etc. All based on NeHe's lesson 24. But I left the code alone for some time, and when I came back, I realised the code was such a mess that I had no idea how was I suposed to implement a GUI of some sort... after all, my code was huge pile of copy&paste material. So I forgot completely about my game, got back to cplusplus.com and started learning c++ all over again...

Yes, all my source codes were big Frankenstein monsters, and maybe it's all the tutorials fault. But I learned a lot just by messing around with my Frankenstein's guts. To be honest, I don't think I can even build an OpenGL aplication by myself yet, but the fact that I have a program that allows me to draw triangles in the screen has let me to build a heightmap on top of GameTutorials OpenGL 6 tutorial (it was a tutorial teaching you how to implement a free moving camera in real time.). And the lighting of the terrain was actually built by myself (ok, almost, I got the lights from NeHe, but made the normals myself), while the camera.. was a complete rip-off from CodeTutorials (and since then, all my cameras have been CodeTutorials rip-offs..).

So I believe that what we have here is just newbies walking around with codes too complex for them to understand, and the problem is that they think they wrote that code, while they did not. However, once they realise this, I don't see much problems from copy&paste tutorials.
July 20, 2006 05:06 PM
You must log in to join the conversation.
Don't have a GameDev.net account? Sign up!
Advertisement