User: Password:
|
|
Subscribe / Log in / New account

Re: An open letter to Evgeniy Polyakov

Re: An open letter to Evgeniy Polyakov

Posted Nov 27, 2008 4:01 UTC (Thu) by lipak (guest, #43911)
Parent article: An open letter to Evgeniy Polyakov

One of the things that encourages people to write code but not worry
about documentation is statements like:

Talk is cheap - show me the code

As a pithy slogan it may be good, but it _could_ give the impression
that writing code alone is enough. This is especially tempting
when writing code comes easier to you than writing documentation.
On top of this uber-hackers tend to dismiss code cleanup,
documentation etc., as low-hanging fruit.

The point that Harold Welte made in his FOSS.in talk this year is
worth recalling here. (It seems to be to also be an undercurrent in
the article being commented on.)

The best FOSS code is written to be read by other humans

Of course it _should_ also run efficiently on a real computer
and so on, but FOSS code that is not a good read is not reviewable
or maintainable.

To make this easier for those for whom English is not a comfortable
language, we should ask the following question:

Will reviewers be willing to accept documentation in languages other
than English?

Kapil.


(Log in to post comments)

Re: An open letter to Evgeniy Polyakov

Posted Nov 27, 2008 7:09 UTC (Thu) by i3839 (guest, #31386) [Link]

The question isn't whether reviewers are willing to accept non-Enlish documentation, the question is if people review stuff they don't know what it is nor what it can be used for. You need to spark some interest before you get some attention.

Next step is to make it as easy as possible for people to try the stuff out. High quality documentation that explains briefly how it works and how to get it working is crucial here. the shorter the better, as it in general means it's easier to setup.

In the case of distributes storage it should be made clear what problem is solved and what the advantages are compared to similar solutions, like distributed filesystems.

At this point you'll get people interested enough to help you with the code, either writing parts of it or reviewing it. Or at least a bunch of users.

Re: An open letter to Evgeniy Polyakov

Posted Nov 27, 2008 9:24 UTC (Thu) by rvfh (subscriber, #31018) [Link]

> The best FOSS code is written to be read by other humans

Correct code (including comments) is written to be read by others, because at some point someone will want to add a feature or fix a bug or make it more efficient.

Also because, in two months/weeks/years time (depends on people), the writer will have gone to some other activities and won't be able to understand that ugly clever trick they made to fix that strange case they don't quite remember all the details of.

Also because compilers will have trouble reading too it if it's badly written, and may optimize it in unexpected ways...

Re: An open letter to Evgeniy Polyakov

Posted Nov 27, 2008 11:05 UTC (Thu) by rsidd (subscriber, #2582) [Link]

The best FOSS code is written to be read by other humans

Or, as Abelson and Sussman put it (in the preface to SICP): "Programs must be written for people to read, and only incidentally for machines to execute."

Re: An open letter to Evgeniy Polyakov

Posted Nov 27, 2008 11:13 UTC (Thu) by hmh (subscriber, #3838) [Link]

"Will reviewers be willing to accept documentation in languages other
than English?"

Probably, but what would be the point? The code won't be accepted in that state on mainline anyway... so you're more than likely to just get a "translate to english first, please", or to be completely ignored.

Not that I like the "completely ignored" thing, but...


Copyright © 2017, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds