Seen so many articles here and many of them have just the code No external links, no demo, no screenshots related to the articles, or the code for the program Would you prefer reading a plain article with just the code? or You would like to have something else also, except the code? Like it's said "pictures speak a 1000 words", wouldn't it be good if: we also attach screen shots of the working of the program? OR some external link which has demo of the program? OR the working program attached to the article? OR something else, which gives a fair idea of the program to them also who don't know that language but would be interested in having a look at the article. What do you guys think?
Writing good code articles is quite difficult because there is a lot more than just writing the code that has to be done for the article to be any use. Posters like amanbua and others like him are only interested in posting the code, they've completed the program and are pleased with that, and want they want is for people to respond with "wow, you're such a kewl l337 d00d", but they're not interested in actually helping people understand how and why the code was written the way it was. The code itself needs to be neatly written, properly indented, with sensible variable names and lots of sensible comments. So Code: int z; for (int p=z=0; p<20;) { z+=f[p]; p++; // increment p } int q=z/20; fails on all these counts. What are z, p, f, and the significance of the number 20? We know p++ increments p simply by looking at the code but what is the point of the line? A better example: Code: // Find the average of the stats array int total=0; for (i=0; i<STATS_SIZE; i++) { total+=stats[i]; } int avg=total/STATS_SIZE; In this case it's clear that i is just a throwaway loop variable that just gives us access to individual members. avg is clearly short for "average" and we know we're finding an average from the comment. The article should contain the code plus a description of what the code is for and a high level overview of how it works. This description is a higher level than the comments in the code; you wouldn't in the description necessarily mention the need to get the average for stats[], but it should be clear from the high level explanation of the code why we need to get the average of that array. The reader should understand the high level implementation of the code before starting to look at it, and the code comments should describe the implementation and relate that to the high level design. The code should also be as portable as possible. For most demo code pretty screen displays are not needed, so we can dispatch with all the Turbo C gotoxy() calls and so on. Code should run unchanged on Linux, Windows and other OS's, and should work with all the major compilers. You cannot and must not assume that your readers have the same compiler and OS setup as you. Testing on them all can be difficult, but if the code is generic enough (and clearly documented) then it will be easy to tweak the odd platform-dependent part for any new setup. Other stuff you've mentioned: > we also attach screen shots of the working of the program? Depends on the code. If the code demonstrates how to write a linked list, then a screen shot isn't really going to add much. But if it's a demo of different asterisk shapes then yes the output (not necessarily as a graphical screen shot, a simple copy and paste would do the trick) could be useful. > OR some external link which has demo of the program? Interesting idea, but if the code is correctly documented and commented, then the reader will be able to understand the code. Yes, if the demo is a useful ADDITION TO (*not* replacement for) the high level description. > OR the working program attached to the article? No, it would be too easy for someone to hide a trojan or virus in that; also executables are very platform specific and your Turbo C compiled executable would not work on my Linux box. Give commands to compile and link the program if you want, but again those are compiler and platform specific, and should be the subject of another article. > OR something else, which gives a fair idea of the program to them also who don't know that language but would be interested in having a look at the article. High level description plus implementation details in the code comments would cover this.
Shabs: Agree with your point, but I'm not talking about the documentation, and even I hate that :lol: I want to say that if you attach your code, and if it's not a Hello World program, how is one supposed to understand the code and rate/discuss/nominate the article. Instead if there is atleast some screenshots of the program working, any one would come to know easily what does the program do and how it can be helpful.
Totally agree with your point, and that was the reason for this thread I've mentioned all the points with OR so even if one thing is there which can help users to gain some knowledge about the article, it would be great
