Etcsrc: Frequently asked questions

From /etc/src/
Jump to: navigation, search

Contents

Introduction to CodeMinima

What is CodeMinima?

As a programmer, an essential task while writing code is finding good code samples for implementing a particular mechanism. Unfortunately, most code samples found on developer sites tend to be bloated with extraneous stuff that does not really contribute to the understanding of the pertinent concept. What is needed is really lean code that helps the software developer understand the concept at hand without factoring in unnecessary complexity and irrelevant lines of code.

CodeMinima.com is a site that attempts to address precisely this frustration faced by developers. It is a code-samples site with a difference: it presents the developer only the bare minimal amount of code needed to understand and implement a concept. It is styled like a wiki, very similar to Wikipedia, and is meant to be a community effort where developers help other developers and the community at large by submitting code samples in a pre-defined format.

CodeMinima is independent of languages, platforms, and operating systems, and aspires to have code for any and every programming language like Assembly, C, C++, Java, C#, VB, VB.Net, Perl, Python, Ruby, Lisp, Clojure, Erlang, SQL, Regex, Shell scripts, and so on and so forth.

Why the name "CodeMinima"?

Because, as the name implies, this is a minimal code site. Our attempt is to offer precisely the minimal amount of code required for a software developer to understand how to implement a concept. CodeMinima's aim is to have short, concise and to-the-point code samples, eventually for any and every programming language and for every domain.

As software developers, we realize the amount of frustration we go through while searching for workable code without having to understand a program that stops just short of simulating the Houston Space Center, to understand that one small bit of code that we're looking for. We are sick and tired of 500-line program code samples when actually what we are looking for is a simple explanation that will not take more than a dozen or so lines of code. Time is at a premium, and when, as a developer, I am looking for a piece of code, I am looking for that piece of code. Period.

As a community our endeavor on CodeMinima is to have code samples that are absolutely minimal in size (hence the name CodeMinima) so that additional and unnecessary complexity is eliminated. In short just the minimal amount of code.

Isn't toy code bad?

Sez who??? As a programmer, I absolutely love toy code. Because, if I am looking for a full-blown working program to understand a concept, then I think I may be in the wrong profession. Toy code should be enough for a programmer to get them started off with the mechanics of implementing a concept, but if they are looking for a full-blown program to understand how the concept could be applied, then maybe a beginner-level textbook would be more appropriate for them.

Which languages do you have code for?

Our endeavor is to have code samples for any and every programming language regardless of its syntax, platform or operating system. So you will soon enough find sections on languages like Assembly, C, C++, Java, C#, VB, VB.Net, Pascal, Perl, Python, Ruby, Lua, Erlang, Lisp, Clojure, SQL, XML, Regex, Shell scripting languages, and so on and so forth.

Why is this site a wiki?

Because it is meant to be a community resource, where anyone who has anything valuable to add can do so without having to ask anyone. Secondly, in case there are any errors in the sample code, the community can come together to rectify it.

And insofar as wiki syntax is concerned, we are quite assured that the community using this site should have no problems learning it, since both the resource producers and resource consumers belong to a highly skilled technical group.

Why is this site a Wikipedia clone?

There was a very strong and deliberate reason for giving this site the same look and feel as Wikipedia's: We want you to know that the same skills that enable you to add stuff on Wikipedia can be ported here, and vice-versa.

Signing-up

Do I have to sign up for using this site?

The short answer is, no, it's not necessary if all you are looking for is a code sample. However, if you feel that you can contribute in any way, please feel free do so, and for that you will have to sign up (see next question).

How do I sign up?

Signing up is easy. Just use the Log in/create account link at the top-right of this page and you're good to go.

Contributing

How can I contribute on CodeMinima?

If you feel that you can contribute in any way, the first thing we would like to say is that we are grateful for your decision, not just for this site but also for the fact that by deciding to contribute you have taken one step forward to help the software developer community, and for this, Congratulations!

To contribute a code sample, please do the following:

  1. Sign up to create an account;
  2. Search for the particular code sample in the Search box near the top-right corner, for example, Java: How to do so-and-so;
  3. If an article exists for that, it will be displayed in the search result; if not, you will see a red link like so: Create the page "Java" on this wiki!;
  4. Click on the link and you will see an entry template for entering the code sample;
  5. Check out some other code samples on the site that could act as reference entries;
  6. While entering the code samples please keep the rules in mind.

But I am not a wiki expert! Where do I start?

Well, neither is any of us a wiki expert. But we learned, and are still learning. The good news is that to get started you need to know just a very bare minimum of wiki syntax, which is not more than a single page in length! In any case we're not really worried about this being a problem for software developers, since this site's producers (and consumers too) are technically-inclined people, and understanding MediaWiki syntax should not really be too tough for them.

Check out Wikipedia's cheat sheet here which presents the wiki syntax in a minimal form. You can even download the cheat sheet as an image from here: Media:Page1-282px-Cheatsheet-mediawiki.pdf.jpg. However, if you are looking for a more detailed explanation, please see the next question.

Where can I learn the MediaWiki syntax from?

For a detailed explanation have a look at out CodeMinima's general help page. More specifically, the formatting and editing help pages explain how to format and edit your page.

Any good books on MediaWiki?

Check this out. It is one of the best books on MediaWiki and possibly a timeless one at that.

Do we absolutely have to use the pre-defined template while entering code samples?

No, you don't have to, other than the title within the tag and the Description tag right at the top of the page, both of which are mandatory. You can just get rid of the the others that you don't need. You can also add your own title tags as you see fit.

A couple of other things: there is an Author link tag towards the end of the entry template that automatically inserts your CodeMinima user name at the end: we wouldn't recommend that you remove that. Following that is the Template:Signoff template for adding social media links so that people can add their comments about your code sample on Facebook. We would request you not to remove that either.

What is the format for submitting code samples?

There are two things to keep in mind here: one is for the page link and the other is for the page itself.

While typing the search term in the search box, use this format: MySQL: How to get the row count in a table, that is, suffix the query with the language name or the product name (in the example here it is MySQL), followed by a colon, followed by the query that specifies what you are looking for. If you have used MediaWiki for any amount of time, you will know that the search query itself can be made into a page link. So the example we just used should become a link like so: MySQL:_How_to_get_the_row_count_in_a_table (this will be suggested by the wiki software, with the legend MySQL:_How_to_get_the_row_count_in_a_table in red). Click on the link and you can start adding your entry. One caveat though: Be careful while adding entries for the C# programming language. Do not use C#: How to do so-and-so, since the hash ('#') sign has a special meaning when applied to URLs. Rather, use the query CSharp: How to do so-and-so.

For the page format, I would recommend that you have a look at any of the current pages depending on the particular entry type which can act as a reference for your own entry.

What kind of heading should I use for my code samples?

Please bear in mind that the heading that you choose becomes the URL of your code sample. So be careful in your choice of words!

You can look up examples of good and bad headings within this wiki itself. The bad ones have been retained for both historical reasons as also the fact that they've been indexed by search engines already.

Imagine yourself on the other side of the fence, that is, you are using a search engine looking for code that helps you do something; let's say you want to figure out how to use the AE.Netmail open source .Net library for receiving emails. From that perspective, which of the following headings (as they appear in search engine results) make sense?

Of course, the second heading is more telling, since it explicitly tells us exactly what it delivers, like receiving emails using the library in question in this case. I am not a search engine optimization expert, still I will venture to say that you should bear in mind that the URL of the site link too helps the search engine figure out its relevance as a solution to the search engine user's problem at hand. (BTW, the exact URL of the AE.Netmail thingy above is here.)

A good heading tells us (nay, promises us!) exactly what the body that follows it promises to deliver to the information seeker. So please put a lot of thought in this aspect of your program sample!

What is the best way to explain the code samples?

To paraphrase the well-known proverb a single section of code is (or should be) worth more than a thousand lines of documentation. Keeping this in mind, we can say that:

  1. The best explanation and the best documentation for any piece of code should be the code itself;
  2. The second best option is to explain the code inline within comments;
  3. The last and the worst way of explaining how a piece of code works is by using an external document.

I have tried -- or at least am trying -- to use the first method (the code is the document) within all the code samples that I submit on CodeMinima. To that end, I try not be too clever and thusly avoid using shortcut methods. To take a practical example, I recently avoided the temptation to be clever in the interests of program maintainability. Quite possibly I may well be the guy who will eventually maintain the code base and I don't want to end up cursing myself.

    bool ignoreDiscountedRate = false;

    if (discountedRate == unitRate) {
       ignoreDiscountedRate = true;
    }

Simple enough; but I could have been clever like so:

    bool ignoreDiscountedRate = discountedRate == unitRate;

The same thing accomplished in just one line of code. However, since I was more concerned with maintainability than impressing myself with clever code, I opted for the longer but more readable piece of code; while it is longer, it goes a long way in terms of being understood by the programmer who may later happen to maintain the code and who may quite possibly be a novice.

Again, I am aware that this is purely a subjective matter (for example, the latter "shortcut" line is more intuitive for me). One thing to bear in mind, however, is that most compilers today are "smart" enough to generate the most optimized code. So I may well assume that the compiler will generate more or less the same byte code in both cases. So if I have to err, it makes more sense to err on the side of readability. Being explicit is always better than being ambiguous. This is just a sample case, but I hope it's illustrative.

On CodeMinima we want to put code that will be understood by all, the most common denominator of programmers, newbie or otherwise, though that may not always be easily accomplished. So the next best option is to have inline comments that practically hand-hold the reader into understanding the code line-by-line or at least function-by-function. Most of my code samples are in this style.

Lastly, we do have an almost mandatory Explanation section for explicitly explaining what has been achieved in the code sample.

What if the code sample I have submitted is incorrect?

Don't you worry, the community is here to take care of that! That's the whole point of this site being a wiki, and not a simple content management system. We are all here to help each other. So don't really let that bother you. Just do the following if you are unsure about the validity of your code: Add the legend: BETA in red to the code sample page so that others are warned. The community will then ensure that the code is eventually corrected.

Does this mean that the code samples on this site are unreliable?

Far from it! Let us explain. When we say that this site is perpetually beta, it does not mean that the code samples here are unreliable; rather each and every line of code on CodeMinima is a work in progress, since we don't just want workable code here, we want workable and minimal, and therefore more understandable, code. Our aim is excellence! And while excellence is a worthy goal to have, bear in mind that it is a constantly moving target.

What are the rules for contributing a code sample?

The rules are very simple, really: The rules for submitting code samples are very simple:

  1. The code should be working: it need not be complete, with a main program that calls it; it could simply be in the form of a function;
  2. The code should be absolutely minimal, no frills, or bells and whistles;
  3. If at all you have to use some static string like, say, the URL of a website, use example.com. Avoid using your name like, say, www.billanderson.tld (assuming that your name is Bill Anderson), because there should be absolutely no scope for confusion to the reader. If you have to use personal names, use common names like: alice, bob, eve, john, jane, and so on.

The most important question for me is, why should I contribute? or What's in it for me?

There are different reasons for different people. Some may do it for recognition within the developer community, while some others may contribute for letting potential employers or contractees know of their skill sets. Yet someone else may be doing it for purely altruistic reasons. We will let you choose yours. The most important thing to remember is that the moment you add even one code sample, you end up with a piece of web real-estate (the user page) that you can use for advertising yourself. (See the last section in this FAQ to know more about the user section.)

Authorship

What if I am not credited for a code sample that has been contributed by me?

That is not possible on this site, since it is a wiki and practically every change here is recorded. However, if you are still worried about not being credited as the original author of the code sample in question, keep in mind that your CodeMinima.com user name will automatically be added as the Author link at the end of your code sample. And if you are keen to let others know about yourself, the user page is for that. (See the last section in this FAQ to know more about the user section.)

How else can I secure the authorship of my code sample?

One excellent way to secure the authorship of your code sample (including its explanation) is by signing up on Google Plus. Once you have done that, all you need to do is to add your Google Plus URI in the Author link section at the bottom of the code sample. Please have a look at a sample author link here. (You can view the code using View source link near the top of the page.)

The Google+ URI is like so: <a rel="author" href="https://plus.google.com/117235482016470457911/">Najeeb Shaikh</a>. Once you have added your Google+ link there, wait for a few days for the Google bot to index your code sample. Once it has done that, you can be sure that the entire content that you have put on that page will be indexed as yours forever in Google's database.

What if I still feel that I have been wronged someway, like my code sample has been "hijacked" by somebody else?

Please let us know by emailing us at I.png@codeminima.com and we will do what we understand as correct after due diligence.

Copyright & Ownership Issues

Will this site be a paid one in the future?

An emphatic no. We do not ever intend to make this a paid site. That's a guarantee we give. We strongly believe that knowledge should be free, and that's the reason we have made this site a community resource. We look at the entire content on this site as belonging to the community as a whole, and the world at large.

Who do the code samples belong to?

All the code samples belong to the community. (See next question.) Under what license are the code samples released?

All the code samples on this site are released under The Code Project Open License (CPOL) 1.02, which essentially means that you can use the code samples on CodeMinima.com any way you like in your application but they may not be distributed or republished without the original author's express consent. Please read the formal text of the copyrights statement. Does that mean that I contribute code samples to this site and lose credit for it?

No, far from it. The whole fun of doing work of this sort is the sense of community standing that it gives you. Nobody, repeat nobody, can take credit away from you once the code sample is in place. Since this site is a wiki, each and every change is recorded in that page's history. So no worries for you on that front.

Is it ok if I add samples that some other CodeMinima user has already added?

Yes, you can do that; after all, we are all looking for better (and, of course, more minimal) code samples. So if you feel your code sample is better, by all means, go ahead and add it. However, it is strongly recommended that you do this only if your code sample differs significantly, and of course is better and more minimal. Remember that on this site less is more!

Can I take code from a book and put it here?

See next question.

Can I yank code off other sites/books and put it here?

No, you cannot do that! Because though we are very liberal about making our code snippets free, others may not be too thrilled to find that their code is being used elsewhere without their permission. Before submitting your code sample, there is an implicit understanding between you and CodeMinima.com that your sample does not violate anybody's intellectual property.

What if somebody's code sample is found to be violating a copyright?

Very simply, if after due diligence we find that this is indeed the case, we will do the following.

  • Remove the offending page;
  • Delete the user's other contributions;
  • Delete the user's profile.

As a community site, we cannot risk jeopardizing CodeMinima -- which is of benefit to the entire developer community -- owing to one user's misdeed. What if I find that somebody's code sample violates a copyright?

If you find a user's contribution violating some third-party copyright, we would request you to please let us know that by emailing us at V.png@codeminima.com, along with the pertinent information like the link to the code sample page, reference to the site/book/material at which the code/work originally appears, and so on. We will take appropriate action after that.

Using & Sharing the Code Samples

Can I use the code samples from CodeMinima.com in my program?

Yes, you can. You are free to use the code samples any way that you want to within your programs, regardless of whether your programs are open-source or proprietary, and you do not have to attribute it back to CodeMinima.com or even mention anywhere in your code that you have taken the sample from CodeMinima.com (although we wouldn't mind if you did that).

There is one restriction, however, and that is you do not re-publish any code sample from here on any other site and claim it to be your own. This last exception is very fair, and we are sure you will agree with it.

Am I legally liable if somebody uses my code and does some damage?

No, not at all. Because anybody who uses this site in any way whatsoever has implicitly agreed to the disclaimer.

Can I add a link to any code sample at CodeMinima.com on my site?

Of course you can. Just copy the URL as it appears in your browser's address bar, and you're good to go. Can I add a code sample from this site on my own?

In the interests of fairness to the contributors, we cannot allow that. However, you are free to add the particular code sample's url on any other site.

Helping the Cause

How can I help CodeMinima?

Thank you for the thought, we really appreciate it! CodeMinima is a community effort and we hope that the community itself takes it forward. The most important thing, however, that we would ask you to do is to either add a review on [http://www.alexa.com/write/review/codeminima.com Alexa.com. Secondly, every single code sample page has a Facebook widget that lets you share and comment on the code sample with your friends on Facebook. Please do add a comment there too, even if it simply just says "good." We will be very grateful for that.

User Page

Can I use my user page to add information about myself?

Yes, you can very well do that. However, we would recommend you do that only once you have contributed at least a few code samples. You can even put the URL of your user page at any site that you please, so that people can read up about you here. In short, you can market and sell your services from your user page.

Will I be stopped if I put my website links here?

No, you won't be stopped from doing that, so long as the sites you link to are related to software development in particular and technology in general. Most importantly, however, they should not link to offensive sites.

Can I use the user page for promoting my consultancy/business/whatever?

Yes, you can. You are at liberty to do so. Of course, it shouldn't be blatant spam, or anything that deviates from the theme of this site. For example, we certainly wouldn't look away if somebody started peddling email lists for spamming. That's just one example, there could be others; You get the idea. Similarly, we do not allow profanity anywhere on the site, nor links to pages that may be considered offensive in any way to any group of people. Always bear in mind that this wiki is a resource for the software community as well as a medium for networking with other professionals.

Will you change the user page policies in the future?

We reserve the right to change any of the policies pertaining to this site. The reason for this is that if we think someone may be abusing our liberal policies, we may feel the need to curtail the undesired behavior. Ultimately, it is in the larger interests of the software development community that we have to enforce any policy.