Talk:How to Write a Program

21st December 2004 (Winter/Summer Solstice)
 * Three jewels:
 * Sequence
 * Selection
 * Repetition

Test cases
I have had a list of common test cases transwikied from Wikipedia because I thought it could be put to good use in this or a similar book. The list can be found at Transwiki:Common Test Cases. It needs a little cleanup, of course, but is in pretty good shape. Hopefully, someone for familiar with this book than me can put it to good use. Thanks --ThaddeusB (talk) 00:33, 6 June 2009 (UTC)

The Style Leaves a Lot to Be Desired - what should I do about it?
Hi all!

I learned about this book, from a link someone placed on the my Optimizing Code for Speed wikibook. Now I agree that reading a good introduction on how to write a program should come before you start optimizing a working code senselessly. (I should note that I haven't encouraged such unwise behaviour in my article, just possibly not stressed it enough.)

In any case, I feel the style of this wikibook and its tone leaves a lot to be desired. It's very unofficial, quite condescending not NPOVish (= Neutral Point Of View) enough (I admit that wikibooks need not be as NPOVish as the wikipedia and may be somewhat biased, but it's still an important partial factor). As a result requiring it as a pre-requisite to mine may leave a bad impression.

But naturally I should not complain if I don't volunteer to fix it myself, and I do. However, I'm not sure my modifications will be accepted by the originators of this wikibook, and so kindly ask for their permission, to fix the style and correct the manuscript. From my wiki-ing experience, I know that sometimes documents that I've started were taken to completely different directions that I've neither intended nor found desirable, which I didn't appreciate, due to a certain feeling of propriety. (Which I hope was not territoriality.). So I'm asking here whether it would be OK.

Shlomif (talk) 11:32, 10 November 2009 (UTC)

I find even the premise of the book a little skewed. According to the book title this is a book about learning how to program, but the contents assume familiarity with languages, so the topic is not how to use the languages to program, but about how to program in an industrial environment where you have Requirements Papers and such like already generated for you.

If we are going to discuss production programming, then shouldn't we cover more than just the basics such as refactoring, and perhaps cover disciplines like Top-Down, Extreme Programming, Agile Programming, etc. techniques? Should we accept the premise that language is not important to the book, or should we discuss the relative usefulness of a number of programming languages in order to give the programmer a background in modern languages other than the ones they learned at school, or should we discuss the use of Structured English, and Flow Charts as tools to organize the program. Perhaps a section on UML might be in order? How about a chapter on profiling and how to use it to determine where in the program you want to optimize?

Should we limit ourselves to just programming techniques or should we include Patterns, and links to the rich information sources that have been developed in relation to that discipline? I think that books that have to be used as pre-requisites for other books, should be held to a higher standard than this book seems to be.--Graeme E. Smith (talk) 15:09, 14 November 2009 (UTC)


 * Dear Shlomif,
 * I totally agree with practically everything you have said.
 * In particular, a good introduction on how to write a program should come before learning a bunch of optimization tricks.
 * I also agree that this particular wikibook is not yet a particularly good introduction.
 * Is there some other wikibook that would make a better introduction?


 * We have many Wikibooks about specific programming languages -- Python, Lua Functional Programming, etc.
 * I've been assuming, based on the title, that this wikibook "How to Write a Program" is intended to discuss the sorts of things that are important for every programmer to know, but are not specific to any one programming language -- and so get very little notice in those books about some particular programming language. Things like version control, automated testing, colored syntax highlighting, pair programming, handling bug reports, estimating time to fix a bug, estimating time to add a new feature, how to divvy up parts of a program among a bunch of programmers, etc.
 * Some teachers try to teach these things before getting to the language-specific stuff, but it seems that these things make more sense to students after they've learned to write a few small programs in some specific language.
 * shouldn't we cover more than just the basics such as refactoring, and perhaps cover disciplines like Top-Down, Extreme Programming, Agile Programming, etc. techniques? Yes, that is a great idea.
 * Should we ... discuss the relative usefulness of a number of programming languages...? While such a comparison would be really useful, I think this book should stick to non-language specific stuff -- perhaps the Computer Programming book or Programming Languages book is a better place for those comparisons.
 * How about a chapter on profiling Also an extremely useful technique, but -- perhaps the Optimizing Code for Speed book is a better place for that chapter.
 * I want everyone to feel free to make any and every kind of improvement to this book.
 * As long as you Wiki: AlmostNeverDeleteHumor.
 * --DavidCary (talk) 03:30, 20 November 2009 (UTC)


 * Well, I've started the rework of this book when I've ran into a little Browser-related Yak-shaving and now I'm back. However, in the meantime, I've concluded something else. I had written an essay titled "What Makes Software High-Quality?" (written in DocBook/XML and under CC-by - possibly wikibooking material) which contains four sections: an Introduction, a list of parameters of software quality, a list of ways to achieve software quality, and finally an evaluation of the quality of various Freecell solvers (the latter due to a quote that prompted the discussion in the first place in the introduction and my role as the primary author of a Freecell solver).
 * Now, while the section of the parameters of software quality was supposed to be as comprehensive as possible (and I would appreciate anything you believe is an omission), the other main section about ways of quality did not aim to be comprehensive, but rather give a taste of what people find useful. That's because it's
 * A huge subject. How to write quality software has been the subject of many books, and countless of articles, papers, essays, blog posts, mailing list posts and conversations.
 * A controversial subject. People don't seem to agree on what exactly is the right way to do things.
 * It doesn't appear to be absolutely necessary for one's success (or alternatively to ensure one's success). In the Joel Test, Joel Spolsky says that «Of course, these are not the only factors that determine success or failure: in particular, if you have a great software team working on a product that nobody wants, well, people aren't going to want it. And it's possible to imagine a team of "gunslingers" that doesn't do any of this stuff that still manages to produce incredible software that changes the world.». The plentyoffish.com creator taught himself .NET programming and became a millionaire a year later simply because he had the idea to create a completely-ad-supported web-site, and was the first to market it, but its code probably had left a lot to be desired. And on the other hand, thousands of well-managed projects, products, companies and teams fail each year, and many great web-sites (like my own Perl-Begin appear to be) still destined for obscurity.
 * Back to the topic, if we are going to write a "How to Write a Program" or "How to write Quality Software" or whatever you want to call it wikibook, then we'll have a huge and controversial task ahead of us. Do we cover what we think are the right measures for achieving quality? Do we cover all possible ways to achieve quality and discuss the various opinions about them? In which context do we discuss this: open-source software, commercial software, in-house software, embedded software, games; GUI software, command-line software, libraries and APIs, web-based software, terminal software, client/server; by freelancers, by businesses, out-sourcing, off-shore outsourcing, in-house development, for fun, for profit, etc. etc?
 * It's not an easy question, and I'm not sure we can start tackling it starting from "How to Write a Program" excuse for a wikibook. There are other much more commendable efforts in regards to FOSS development:
 * ESR's the "Cathedral and the Bazaar" and some other writings by him. (Open Publication License)
 * Karl Fogel's Producing Open Source Software - a comprehensive and good book about the topic (CC-by).
 * And naturally, there are many more books and resources about that for non-FOSS development. We should also ask ourselves if we want to add another resource. I think it would be more worthwhile to tackle particular aspects of achieving software quality at a time: speed and efficiency, modular code, readable code, skimmable code, automated tests, tact and social engineering, publicity, picking up a good name, writing comments (or not - some people think code should be self-documenting) bug tracking/triaging/fixing, and other aspects.
 * I think that unless we're planning on tackling that huge problem by writing a definitive resource, then I can safely remove the recommendation to read this book from Optimizing Code for Speed. I guess I can add some text to the introduction explaining the context and risk of optimisation and pointing to relevant resources about measuring and achieving software quality.
 * Would it be agreeable? Shlomif (talk) 23:22, 25 February 2010 (UTC)


 * possibly wikibooking material
 * Thank you for writing that essay.
 * if we are going to write a ... wikibook, then we'll have a huge and controversial task ahead of us.
 * Yes. This is also true for many (most? all?) wikibooks. Have you seen the C++ Programming controversy? :-(
 * In which context do we discuss this: open-source software, commercial software, in-house software, embedded software, games; GUI software, command-line software, libraries and APIs, web-based software, terminal software, client/server; by freelancers, by businesses, out-sourcing, off-shore outsourcing, in-house development, for fun, for profit, etc. etc?
 * Contexts where "Use version control, automated testing, and colored syntax highlighting" is good advice. That's all of them, right?
 * I think there's room for a small book that discusses these and similar widely-applicable programming tips, that we suggest people read just before the "optimization" book.
 * I don't think we should make a huge, definitive book on software quality a prerequisite to the "optimization" book.
 * There are other much more commendable efforts
 * I don't understand. I agree that the current version of wikibook, like the current version of every other wikibook, is inferior to some other work. But I hope that future versions rapidly improve and surpass other static works.
 * I'm not sure we can start tackling it starting from "How to Write a Program" excuse for a wikibook.
 * If you are suggesting starting from scratch, then I suspect you haven't actually read the links you mentioned.
 * One of them says "it's almost always easier to start from a good partial solution than from nothing at all." -- Eric Steven Raymond
 * --DavidCary (talk) 03:06, 18 March 2010 (UTC)