How do you let others trust your code and use it?

Question

I write hobby code from time to time. The thing is these tools, classes or tiny libraries of code end up in a flash stick with hopeless future! I would love to develop my projects further, and let other programmers trust them. If you were going to use something you found on the Internet, what is the most important thing you look for in that programming tool or small library? eg would you consider separate documentation a must?

---

Thanks for all contributers. I'll try my best to summarized what have been said. Feel free to modify the list. Corrections and additions are more that welcome :)

• Start a blog and let others know you are here.

• Choose the most suitable license. Possibly Open Source licenses are the best for hobby projects.

• Put your project where people can reach it. Consider google-code , github , sourceforge or other sites.

• Use public version-control and bug-tracker, So others can acquire the latest source code of your project to compile and use.

• Write a decent documentation, beside commenting your code clearly of course. The documentation should explain the purpose of the library and provide at least simple examples.

• Write tests if you are willing to provide real-world code.

• If you are building a library, put a lot of effort into designing a stable interface.

Answer 1

Get a blog, release code through it. Explain why you wrote it, what problem it solves. And encourage others to improve upon it, keep the code posted as current as possible. If your tools are useful you will very quickly develop a following that 'trusts' your code.

Separate documentation isn't a must for small tools, but anything creeping into the framework world should probably have ample documentation and examples if you want any serious adoption from the community at large.

Answer 2

The most important thing is that the library is that it be open source, so I can read the code myself. If that is not possible then I insist on documentation.

Also consider using a project-hosting site (like google code or github).

Answer 3

1. Have a clear license with your code if you don't have one already (preferably one which encourages modifying / improving / sharing your code ...)

2. Have public version control and/or a public bug/issue tracker and/or a mailing list. There are a lot of good sites which offer these services for free.

3. Seperate documentation is not a deciding factor to me (if the code is well documented and the code quality is high).

Answer 4

• Documentation explaining why you wrote it, when you started it, and it's intended function. Understanding where you're coming from will allow me to see future ideas as well as short coming you may not have seen.
• Technical documentation explaining the API and some examples on how to implement it. Ideally, keep your documentation in the format that follows the language. For example C# tends to use the XML syntax for defining items. This allows me to feel at home when I'm reading it.
• Clean code -- I can't stress this enough because far too many people write exceptionally ugly code. If you're code is ugly and/or unreadable, it may be easier for me to write it from scratch on my own. At the very least, make your code consistent. If I can't understand the code, I won't feel comfortable with it.
• Historical records explaining your changes. Seeing how the project has grown allows me to plan better. It also allows people to see how you learn from your mistakes and get a sense of your skill level. Compared to a forum, you can get a feel for how fast things get fixed and then placed in to a new release.
• Think long and hard on what kind of license you want there. Public domain? BSD? GPL? More restrictive?
• A note on whether or not you mind being contacted and if there are any restrictions in this. For example, would you mind updates? Me explaining security holes? Or perhaps you might use a forum or wiki?
• The ability for me to get your latest work and/or nightly builds. SVN or something. This is useful so I know if a bug I found is already fixed.

Answer 5

I think that documentation is a key point for your project.

The document must indicate:

• what is the purpose of your library
• what are the main features
• a really short tutorial, to make it run in 5 minutes.
• Many examples

Answer 6

I let people trust my code in a number of projects, but I urge people to make and maintain their own tests, and I make sure that I'm content with the unit tests.

Documentation is always good, but I'm very guilty of finding time to do as much as I would like. But having the author fairly contactable is helpful.

Answer 7

Posting it in an open source repository such as code.google.com or sourceforge.net is probably where to start...

Next to attract attention, document clearly and succintly the purpose of the library / application as outline in one of the answer above.

Finally, blogging and direct mail exchanges happen...

Answer 8

One reason documentation helps people trust your code, is that they know whether a given feature is something which you intended the code to do (and which you will, all else being equal, preserve in future versions of the code), or something that the current code just so happens to do, but which might change at any time as a side-effect of a bugfix or just a refactor.

Some people prefer find out what code really does by looking at it, and that's fine, but documentation tells you (a) what the code is supposed to do, and with any luck (b) what the next version of the code will do. If I want to use your code long-term, and take bugfix updates as you provide them, then I need to know that you've designed an interface that I can rely on and that you're willing to stick to. Documenting it is a strong hint that you're at least trying to do that.