Go is not good at..

[Amitabh Arya]

Go is a good programming language so far, I discovered. But there are two things, really not good about it, it may take some more time and gets better possibly if some one is working on it. Or it is good and you can suggest me the better source of it, 

>> The database management: No one can start with go right away writing a big web server or something. Go is really good in that though. But if one is writing a small web application in go for then the database interaction is really bad in go, there is no 5- 10 lines of code to get the data from some table. There are some  third party (beta version) opensource drivers but does not have good documentations/examples. If there are please let me know. 

>> All go documents written out there, are for high level programmers like some one should already know c, or c++ to understand some of those docs. It should be like any one who is working in html/JS/Flash/php or something can understand it.

Give you suggestion or view on this.

[Gustavo Niemeyer]

On Wed, Mar 28, 2012 at 17:46, Amitabh Arya <amitab...@gmail.com> wrote:
> The database management: No one can start with go right away writing a
> big web server or something. Go is really good in that though. But if one
> is writing a small web application in go for then the database interaction
> is really bad in go, there is no 5- 10 lines of code to get the data from
> some table. There are some  third party (beta version) opensource drivers
> but does not have good documentations/examples. If there are please let me
> know.

http://labix.org/mgo

--
Gustavo Niemeyer
http://niemeyer.net
http://niemeyer.net/plus
http://niemeyer.net/twitter
http://niemeyer.net/blog

-- I'm not absolutely sure of anything.

[Kyle Lemons]

On Wed, Mar 28, 2012 at 1:46 PM, Amitabh Arya <amitab...@gmail.com> wrote:

Go is a good programming language so far, I discovered. But there are two things, really not good about it, it may take some more time and gets better possibly if some one is working on it. Or it is good and you can suggest me the better source of it, 

>> The database management: No one can start with go right away writing a big web server or something. Go is really good in that though. But if one is writing a small web application in go for then the database interaction is really bad in go, there is no 5- 10 lines of code to get the data from some table. There are some  third party (beta version) opensource drivers but does not have good documentations/examples. If there are please let me know. 

http://code.google.com/p/vitess/

I also use ziutek for MySQL and it works fine.

 

>> All go documents written out there, are for high level programmers like some one should already know c, or c++ to understand some of those docs. It should be like any one who is working in html/JS/Flash/php or something can understand it.

Go's documentation, to my view, is remarkably good for how young the language is.

[Russ Cox]

Thanks for your comments. I think you're right on both counts.

On Wed, Mar 28, 2012 at 16:46, Amitabh Arya <amitab...@gmail.com> wrote:
>>> The database management: No one can start with go right away writing a
>>> big web server or something. Go is really good in that though. But if one
>>> is writing a small web application in go for then the database interaction
>>> is really bad in go, there is no 5- 10 lines of code to get the data from
>>> some table. There are some  third party (beta version) opensource drivers
>>> but does not have good documentations/examples. If there are please let me
>>> know.

It's true. The database support is weak right now.
We worked hard to get the database/sql API defined and working
in a form we were willing to commit to, but the drivers for it are still
rough. Now that the sql package exists, though, I think the drivers
will come along nicely. If you say what database you are using,
people here might be able to suggest a good driver. Eventually I think
we will have a subrepository with recommended drivers.

>>> All go documents written out there, are for high level programmers like
>>> some one should already know c, or c++ to understand some of those docs. It
>>> should be like any one who is working in html/JS/Flash/php or something can
>>> understand it.

That's also true. The main reason is simply that you don't have to write
nearly as much if you assume that people have already learned the
concepts of programming and just need to learn the new language.
I think that Go is a great language to use to learn how to program,
though, and if we stick around long enough I'm sure there will be books
targeted at that. We're a small team and don't have the bandwidth to
do that ourselves. http://tour.golang.org/ is a step in that direction,
and if someone wanted to develop a different tour for people who have
never programmed before, I think we'd be happy to support that effort.

Thanks again for your comments.
Russ

[Amitabh Arya]

Generally most people try mysql and sqllite I guess, because both are good and opensource database and provide initially all needed functionality. In my case I like to use mysql to interact the database for the web applications. And sqllite for web server itself for local data storage. 

I only find http://code.google.com/p/go-wiki/wiki/SQLDrivers this. Is there anything else and better.. with example and docs.

http://code.google.com/p/go-wiki/wiki/SQLDrivers 

[Brad Fitzpatrick]

On Wed, Mar 28, 2012 at 2:48 PM, Amitabh Arya <amitab...@gmail.com> wrote:

...

I only find http://code.google.com/p/go-wiki/wiki/SQLDrivers this

Those are the current recommended drivers.

 

. Is there anything else and better.. with example and docs.

Here's an example of using the ziutek MySQL driver:

http://code.google.com/p/camlistore/source/browse/pkg/index/mysql/mysqlindexer.go

Your imports should be:

import (

          "database/sql"

....

         _ "github.com/ziutek/mymysql/godrv"

)

Then you open like:

db, err := sql.Open("mymysql", is.database+"/"+is.user+"/"+is.password)

[André Paquet]

On Wednesday, March 28, 2012 3:46:35 PM UTC-5, Amitabh Arya wrote: 

>> The database management: No one can start with go right away writing a big web server or something. Go is really good in that though. But if one is writing a small web application in go for then the database interaction is really bad in go, there is no 5- 10 lines of code to get the data from some table. There are some  third party (beta version) opensource drivers but does not have good documentations/examples. If there are please let me know.

Maybe Go isn't good at SQL (to be honest, I don't know, never tried it out), but it doesn't mean it's not good at databases. You can't beat Gustavo's mgo. Try it

 

>> All go documents written out there, are for high level programmers like some one should already know c, or c++ to understand some of those docs. It should be like any one who is working in html/JS/Flash/php or something can understand it.

 

I think Go's documentation is very good, but my background is C++ so there goes my point. Sometimes the best documentation is code. I find myself reading the std library code when I have trouble understanding something. It reads really well.

 

[Guillermo Estrada]

If you say what database you are using,
people here might be able to suggest a good driver.  Eventually I think
we will have a subrepository with recommended drivers. 

I would like you (community) to recommend me the best (usability/performance) SQLite driver you have tested. I have tested some:

https://github.com/gwenn/gosqlite 

https://github.com/kuroneko/gosqlite3 

And I've been working with them, but documentation is poor at most, having to deduce from tests the usage of the package. And building sqlite library to work with cgo on Windows (even more if setting up MinGW and MSYS on x64) is kinda messy for devs with dynamic language background. Still I got it working. I would love if someone shipped sqlite library binaries to work with, not just the dll. Or is there a way to obtain them from the precompiled dll on the page? If that can be done I would be happy to make wrappers and bindings for some C libraries I know that are small and simple if I can avoiding building them myself from source on Windows.

BTW mgo is by far the best driver around for ANY database around for Go. Thanks Gustavo for such a nice work with that.

[Brad Fitzpatrick]

On Wed, Mar 28, 2012 at 3:29 PM, Guillermo Estrada <phro...@gmail.com> wrote:

If you say what database you are using,
people here might be able to suggest a good driver.  Eventually I think
we will have a subrepository with recommended drivers. 

I would like you (community) to recommend me the best (usability/performance) SQLite driver you have tested. I have tested some:

https://github.com/gwenn/gosqlite 

https://github.com/kuroneko/gosqlite3 

The link to the recommended drivers earlier in this thread contains this one:

https://github.com/mattn/go-sqlite3

... and it passes the go-sql-test test suite, too.  That's what I would use.

I don't know about the others.  If they pass the test suite I'd love to hear it / have them added.

[Guillermo Estrada]

The link to the recommended drivers earlier in this thread contains this one:

https://github.com/mattn/go-sqlite3

... and it passes the go-sql-test test suite, too.  That's what I would use.

I don't know about the others.  If they pass the test suite I'd love to hear it / have them added.

I saw this one too, but I didn't use it because it needs pkg-config

# pkg-config --cflags sqlite3

exec: "pkg-config": executable file not found in %PATH% 

From the MinGW FAQ:

How do I get pkg-config installed?

• The difficulty in getting pkg-config installed is due its circular depency on glib. To install pkg-config, you should first install the GTK-runtime, the installer is found at http://sourceforge.net/project/showfiles.php?group_id=121075. The pkg-config binary can be obtained from http://www.gtk.org/download-windows.html. Place pkg-config.exe in your MinGW bin directory.

The binary link is 404, and it seems like a lot messier at the time under Windows, that is why I went with the other 2 that compile with no trouble once I got my SQLite library built and installed. I read the doc about the goals of the drivers based on sql/database, I think that ease of installation should be added to the list. Now that Windows is a supported operating system, please support us too :D. Anyway, this one is just the driver, the other 2 I mentioned have some nice wrappers around it too.

[Archos]

On Mar 28, 9:46 pm, Amitabh Arya <amitabhary...@gmail.com> wrote:
> >> All go documents written out there, are for high level programmers like
>
> some one should already know c, or c++ to understand some of those docs. It
> should be like any one who is working in html/JS/Flash/php or something can
> understand it.

This is a great and simple tutorial:

http://go-book.appspot.com/

[kortschak]

On Thursday, March 29, 2012 7:16:35 AM UTC+10:30, Amitabh Arya wrote:

>> All go documents written out there, are for high level programmers like some one should already know c, or c++ to understand some of those docs. It should be like any one who is working in html/JS/Flash/php or something can understand it.

I've found the documentation to be some of the clearest and easiest to understand that I've ever come across. While I have some experience C/C++ I am by no means fluent in either - yet I have no problems with the docs. I think that because of the nature of idiomatic Go code being what it is, in most cases reading the docs in conjunction with the source - facilitated by godoc - is the way to understand the expected use and behaviour. The increasing use of examples in the docs also is a help.

[brainman]

On Thursday, March 29, 2012 9:49:55 AM UTC+11, Guillermo Estrada wrote:

I saw this one too, but I didn't use it because it needs pkg-config

# pkg-config --cflags sqlite3

exec: "pkg-config": executable file not found in %PATH% 

 I think there are 2 problems here as far as https://github.com/mattn/go-sqlite3 on windows is concerned:

1) There is no documentation on how to build the package. When the package is pure go, that is OK. But this package is not. It involves downloading all sqlite source (C) and building it into a form usable for cgo. This will require tools that are not available on standard Windows pc. It is completely unrealistic to expect average Windows user work it all out on their own.

2) I do not use sqlite with Go. But I use it with other languages. And the way I access sqlite functionality is by employing a sqlite dll (http://www.sqlite.org/download.html). Perhaps we can provide similar functionality. The advantage here will be that driver will be pure Go - do not need mingw and friends. Deployment would be harder - you would have to make sure to delpoy sqlite dll. But that is sometimes acceptable. Perhaps, "use sqlite dll" mode can be incorporated into existing driver, so it is a matter of recompiling your program to switch from one mode to the other.

Alex

[Guillermo Estrada]

Go documentation is great, and even better, reading the code to understand the standard library is pleasant. But I do have to say that documentation on cgo or how to build some libraries that expect you to have a full C toolchain, is lacky, and having to do that for a PHP or JS guy would be a no go, even more on Windows. I choose Go, because I wanted to run away from C as far as possible (at least that is my story), I dig Ruby, Python, PHP, Java, and I love Go! But I have to say that having to solve so many things before I can even try to start using OpenGL or SQLite or all sorts of things have been a pain in the ass, even more as a Windows dev. I know that D language has a project I used a lot, with the ability to load shared libraries at runtime and you only had to create the bindings to the library in D. It's called Derelict (http://www.dsource.org/projects/derelict). That truly made my life in D a bliss, I wrote bindings for SQLite, GLFW, BASS, and so on by just reading header files of those libraries and applying some rules to port them to D. Now I don't use D anymore in favor of Go, but that was an awesome way I could get going with most C libs. I wish that I can make something about that, but it would be awesome to have something to just load the shared library (.dll, .so, etc...) at runtime, then any .dll binary I download for windows can work without having to build every library myself.

This is not in anyway complaint or anything. I'm happy with Go, I love the language! I'm just sad I have to start installing and learning how to build and configure C after running so much from it, being on Windows just make it worse.

[Starfish]

I want something like LINQ, but that would require some new language
features.

[ajventi]

It's no easy task to write a general database API. Even among the
standard SQL databases they each have their differences that can't be
generalized. I'm currently in the process of a bottom up database
design founded on PostgreSQL, and have ended up here using go to write
some of the middleware. I had to design bottom up, because the
integrity of the database was the mose critical aspect of the
application, which is why I chose Postgres. What I've found in many
languages is people try to put far too many bells and whistles into
their idea of an ideal database library. In many cases the result may
be good for some, but personally I found far too many libraries that
had a whole lot of what I didn't want, and not all of what I do want.

So far working with go, I was easily able to write a small wrapper
around the pgsql.go package to make it suit my needs. Now with the
update to Go1 I may be able to explore a different, and better
interface.

I can see documentation is not great for a beginner, but as was said
previously, it's very mature for such a young language. If you are a
beginner programmer, my advice is don't be committed to one language.
If you think you have a future in programming, you will be using many
languages throughout your life, some you like, some you love, some you
hate and some you tolerate.

I think it may be a bit tough to understand some of the documentation
if you come from a JS/PHP/HTML background (IDK Flash) since JS and PHP
are not strongly typed languages. There are no pointers any many times
it seems easier. Personally I'm not a big fan of the "strongly typed"
languages the way go presents it but it's much more like the C family
of languages, so it helps to have some experience there.

[Nigel Vickers]

I think Russ Cox is being a little hard. His comments may be
applicable if "Database" == "SQL" but I also use Gustavo's mgo and
have little or no issues.

[mattn]

updated README.

[Guillermo Estrada]

updated README.

Just a comment on that, pkg-config depends on GTK runtime libraries too, specifically libglib-2.0-0 and God knows what else. Problem with this kind of configurations is that just downloading the pkg-config executable under windows is not enough, it won't run. apart from having to build your own SQLite lib with SQLITE_ENABLE_COLUMN_METADATA for it to work under windows, and if you're in amd64 well.. there's that. For those trying to build libraries under 64 bits I recommend TDM-GCC 64 installed side by side with standard MinGW and MSYS, you just have to configure MSYS to work with it.

http://tdm-gcc.tdragon.net/download

I agree with brainman that it should be a way to enable developers to just use the .dll's they download without having to setup MinGW and friends to build their libraries. It's a long tedious process filled with unpleasant experiences not Go related. After all, we don't have apt-get. And if that's the case, avoid using other build configuration packages like pkg-config.

[Guillermo Estrada]

On a side notice.

About this issue:

https://github.com/mattn/go-sqlite3/pull/2 

And this change:

https://github.com/lye/go-sqlite3/commit/6a23a746e13aac7dfedb85b5c12db17533b420e0 

If just reverted it back using standard LDFLAGS and it installs without problems under Windows (after building sqlite of course). I don't think adding layers of complexity to installation is the way to go, just because it works out of the box on FreeBSD, it makes a scavenger hunt of executables and dependencies under Windows.

Going to try it now :D thanx for the driver mattn!

[mattn]

How about this.

This is simple pkg-config implementation.

https://gist.github.com/2233549

[Guillermo Estrada]

How about this.

This is simple pkg-config implementation.

https://gist.github.com/2233549

Sounds good for me, I'm going to try it later. Thank you for the tool. 

[L Campbell]

That was my pull request; sorry for breaking the Windows build :/

I think the crux of the issue is that we're either not using cgo in a
portable way, or cgo isn't yet that portable. I'm not familiar at all
with Windows so I'm not sure how the cgo works there (e.g., does it
require MinGW/Cygwin, or is it standalone?). On the *nix side, you can
have multiple versions of a library installed (albeit, this
configuration is uncommon); pkg-config will select the correct one.
Even if multiple versions aren't installed, there are very many places
a library might be installed (arguably, too many to enumerate). What
we need is a platform-independent way to tell cgo which libs to link
in without explicitly relying on having pkg-config.

So, my questions to the list are --

1. Does cgo already have this functionality built in? If so, how can
we leverage it?
2. If pkg-config doesn't exist, is it safe to assume the
library/headers are already in the configured search paths?
3. If it doesn't, can we add a fallthrough option that checks first
for the pkg-config tool, then falls through to manually-configured
LDFLAGS? e.g.

#cgo pkg-config: sqlite3 || LDFLAGS: -lsqlite3

(or something more syntactically elegant)

(this may deserve a separate thread)

[si guy]

I too, would like to use linq in go(to run on maps), but I don't see that ever happening.

[André Moraes]

Search the mailling list for "Go book", I saw that topic not long ago
and the book was compatible with Go1.

I didn't read the book but the topic list looks very good and could be
a great help for those new to Go or programming in general.

--
André Moraes
http://andredevchannel.blogspot.com/

[Remi Gillig]

LINQ is just syntactic sugar for using the method extensions in System.Linq. Someone on this list made a package for using Lisp like procedures (Map etc.) which are basically the same as using Linq directly. So yes, you can use LINQ in Go ( https://github.com/tcard/functional ) but you have to type it yourself which is good because it does not hide that much the horrible GC allocations that LINQ in .NET does behind a simple syntax.

[Liigo Zhuang]

在 2012-3-29 上午6:22，"André Paquet" <andre....@gmail.com>写道：
>
> I think Go's documentation is very good, but my background is C++ so there goes my point. Sometimes the best documentation is code. I find myself reading the std library code when I have trouble understanding something. It reads really well.
>

No, code is not documentation. If someone found he must reading source code  to understanding something, it means that the documentation is very bad. 

--
by Liigo, http://blog.csdn.net/liigo/
Google+  https://plus.google.com/105597640837742873343/

[Peter Bourgon]

>> I think Go's documentation is very good, but my background is C++ so there
>> goes my point. Sometimes the best documentation is code. I find myself
>> reading the std library code when I have trouble understanding something. It
>> reads really well.
>
> No, code is not documentation. If someone found he must reading source code
>  to understanding something, it means that the documentation is very bad.

-1.

Good code is the best documentation.

[chris dollin]

On 29 March 2012 16:00, Liigo Zhuang <com....@gmail.com> wrote:

> No, code is not documentation. If someone found he must reading source code
>  to understanding something, it means that the documentation is very bad.

The documentation need not be "very bad", just imperfect or not in the
reader's native ear or at a different technical level to that of the reader
or just plain unnecessary, given that the code is sitting Right There.

Different people understand things in different ways.

Chris

--
Chris "allusive" Dollin

[Jesse McNelis]

On Fri, Mar 30, 2012 at 2:00 AM, Liigo Zhuang <com....@gmail.com> wrote:
> No, code is not documentation. If someone found he must reading source code
>  to understanding something, it means that the documentation is very bad.
>

Code is the best documentation because documentation can only vaguely
describe what the code does, where as the code can describe everything
in great detail.

--
=====================
http://jessta.id.au

[Hotei]

Back in the "good old days" when you could "godoc" your own source you had the best of both worlds.  Godoc would provide a "high level" view of the interfaces and usually some discussion and maybe an example if the documentor was nice, and then it gave you links to the actual code if you wanted more detail.  I wonder if we're ever going to see that functionality back in godoc?

[Aram Hăvărneanu]

> Back in the "good old days" when you could "godoc" your own source you had
> the best of both worlds.  Godoc would provide a "high level" view of the
> interfaces and usually some discussion and maybe an example if the
> documentor was nice, and then it gave you links to the actual code if you
> wanted more detail.  I wonder if we're ever going to see that functionality
> back in godoc?

I don't understand what you mean, the current godoc does exactly that.

--
Aram Hăvărneanu

[Stefan Nilsson]

Good code is the best documentation.

Even if you have the time and ability to convince yourself of what the code is doing, this is often not enough. For many projects you need to know that this is, in fact, the intended behavior, and that this behavior will remain. For this you need both documentation and guarantees of the type found in  http://golang.org/doc/go1compat.html. That's why today's release of Go 1 is so important. It marks the first day when Go becomes a possibility for many of us.

[Miguel Pignatelli]

On 29/03/12 16:27, Hotei wrote:
> Back in the "good old days" when you could "godoc" your own source you
> had the best of both worlds. Godoc would provide a "high level" view of
> the interfaces and usually some discussion and maybe an example if the
> documentor was nice, and then it gave you links to the actual code if
> you wanted more detail. I wonder if we're ever going to see that
> functionality back in godoc?
>
>

We still have
http://gopkgdoc.appspot.com/

M;

[Aram Hăvărneanu]

> We still have
> http://gopkgdoc.appspot.com/

What functionality is available in the excellent gopkgdoc that's not
available in the current godoc but was available in a previous godoc?

--
Aram Hăvărneanu

[Hotei]

At one time godoc -http=:8080 -path="my source code path" &

created a webserver .  Not the same result at all if you use the godoc -html > file.htm

The issue tracker said a fix has been "abandoned" when I looked a few days ago.

[Jim Whitehead II]

On Thu, Mar 29, 2012 at 5:37 PM, Hotei <hote...@gmail.com> wrote:
> At one time godoc -http=:8080 -path="my source code path" &
>
> created a webserver .  Not the same result at all if you use the godoc -html
>> file.htm
>
> The issue tracker said a fix has been "abandoned" when I looked a few days
> ago.

Godoc still does that...

godoc -http=:6060 -path=. in my GOPATH and everything is fully visible
through the web interface.

Or am I missing what you're saying?

- Jim

[Hotei]

By "everything" do you mean you can see the source docs/codes from your GOPATH?  Is this codereview incorrect?  http://codereview.appspot.com/5689051/   I gave up trying when I saw that.  I'd be glad to hear it has been fixed but I wasn't expecting to be soon from the tone of the codereview.

[Jim Whitehead II]

On Thu, Mar 29, 2012 at 5:51 PM, Hotei <hote...@gmail.com> wrote:
> By "everything" do you mean you can see the source docs/codes from your
> GOPATH?  Is this codereview incorrect?
>  http://codereview.appspot.com/5689051/   I gave up trying when I saw that.
>  I'd be glad to hear it has been fixed but I wasn't expecting to be soon
> from the tone of the codereview.

Yes, that's precisely what I mean. It's pretty simple:

mkdir /tmp/gopath
cd /tmp/gopath
git clone https://github.com/jnwhiteh/go-luapatterns src
godoc -http :6060 -path . &

When I visit http://localhost:6060 I can see all of the documentation
and source for that package.

What isn't visible there is any of the standard library documentation.
It also doesn't auto-detect GOPATH and include that as an additional
path.
It's a bit rough around the edges, but the behaviour has only changed
a tiny bit (it used to show your packages AND std libs).

- Jim

[Ugorji Nwoke]

Russ took that CL and did a more sweeping change that made things very much aligned.

Around that time, there was some discussion that support for -path was not such a priority as folks are expected to depend more on GOPATH.

So in typical usage, have GOPATH and GOROOT set, and godoc just perfectly, showing all packages out of GOPATH and GOROOT. 

The issue with -path acting as a replacement as opposed to an addendum of paths may be a bug, and I'd suggest filing a bug and see what Russ has to say about it. I know that at a point, there was talk of removing the -path parameter altogether.

[Jan Mercl]

On Thursday, March 29, 2012 6:59:49 PM UTC+2, Jim Whitehead wrote:

mkdir /tmp/gopath
cd /tmp/gopath
git clone https://github.com/jnwhiteh/go-luapatterns src
godoc -http :6060 -path . &

I use just:

$ godoc -http :6060 &

 

When I visit http://localhost:6060 I can see all of the documentation
and source for that package.

What isn't visible there is any of the standard library documentation.

... and at http://localhost:6060/pkg/ I see all of my packages in $GOPATH and also all of the standard library.

 

It also doesn't auto-detect GOPATH and include that as an additional
path.

Here it does (Go 1)

 

It's a bit rough around the edges, but the behaviour has only changed
a tiny bit (it used to show your packages AND std libs).

Once again, it shows both for me.

[Jim Whitehead II]

It's possible that my GOPATH wasn't set correctly, but I was just
trying to show that it did seem to do what he was asking for,
regardless =)

[Hotei]

That's great news - like I said, I'm happy to have it back.  Easy generation of _current_ documentation was/is one of the many things I really like about Go.  You can't force people to do docs, but if you make it easy enough it should "just happen".  Go/gofmt/godoc are big strides in that direction.

[kortschak]

I'd have to completely disagree. One of the most beautiful things about Go is the blurring of the distinction between code and documentation. This comes about (at least in my eyes) from the concise and clear way the code is idiomatically written and the way godoc links from the documentation to the relevant code (it would be nice if relevant tests were also linked, but this is harder - impossible - except in the case of the examples which already are).

It's almost like the designers intended that the source be part of the documentation ;)

[SteveD]

On Mar 29, 10:37 pm, kortschak <dan.kortsc...@adelaide.edu.au> wrote:
> It's almost like the designers intended that the source be part of the
> documentation ;)

Oh, the code is excellently readable, but documentation provides the
higher-order view.

Even nice per-function documentation only goes so far; at some point
you have to write some English explaining how it fits together.

Actually, good _examples_ are the best kind of documentation. But
people focus all their energy on tests, which are often _less_
readable than the actual source. It has always been argued that good
tests are good documentation, but not necessarily - if they are just
unit tests and not showing how the whole thing works together.

A great deal of the frustration people have with the database bindings
comes from this lack of simple examples, which should take ten minutes
to write by author - and in fact, _should_ have written anyway as
integration tests.

steve d.

[kortschak]

On Friday, 30 March 2012 17:34:55 UTC+10:30, SteveD wrote:

On Mar 29, 10:37 pm, kortschak wrote:
> It's almost like the designers intended that the source be part of the
> documentation ;)

Oh, the code is excellently readable, but documentation provides the
higher-order view.

 
That's why I said 'part of'.