Wikipedia talk:WikiProject Computer science/Manual of style (computer science)

From Wikipedia, the free encyclopedia

Contents 1 Wikicode 1.1 Assignment operator 2 And/Or 2.1 Both/And 3 Introduction Example 4 Functional pseudocode 5 <pre> and <code> 6 Concrete Implementations of Algorithms 7 Code Samples

[edit] Wikicode

I've read through the Wikicode debate, and I think any similar effort to define a standard is going to hit similar brick walls. I think the best we can hope for is a decent set of "style guidlines" for pseudocode, and a corresponding effort to try and clean up pseudocode to meet the guidelines. Personally I would have to favour a more mathematical/algebraic style if possible, and generally trying to keep to a fairly loose set of guidelines. I expect this will be a significant point for debate. That's probably going to be a good thing: people who are drawn in to argue can be encouraged to to join the project. Leland McInnes 23:19, 28 January 2006 (UTC)

Yeah, I've read through the same debate, and pretty much came to the same conclusion. My intent in putting the wikicode link there was not to mandateanything, but (a) to make people aware of it, and (b) to provide some "guidance on style", based on existing work. I agree that a more mathematical style would be nice, but, as you say, also a huge point for debate. --Allan McInnes 23:32, 28 January 2006 (UTC)

On the subject of pseudocode: IMHO some of the objections about verifiability raised in the wikicode debates are totally spurious - if the algorithm in question is not original research then the pseudocode should be coming from some known (and preferably referenced) source, such as the Cormen book. Perhaps that's another argument in favor of loose pseudocode guidelines - if algorithms are transcribed in the style of the source material there's less chance of errors. --Allan McInnes 23:32, 28 January 2006 (UTC)

Okay, here's my take on some basic guidelines for pseudocode:

• assignment, comparison, and other mathematical operators should be rendered with proper mathematical symbols wherever possible:

assignment: ←

comparison: =, ≠, <, >, ≤, ≥, etc.

arithmetic: +, -, ×, /, mod, etc.

• control structure keywords should be bolded, comments should be in italics (in addition to whatever other manner for denoting comments is used)
• preferred conditional structure is

if condition then
    code path
else if
    code path
else
    code path
end if

• preferred looping constructs are

while condition do
    code block
repeat

and

for loop_control do
    code block
repeat

where loop_control is any suitable clause to control a for loop, such as item in list or 1 ≤ i ≤ n etc.

Feel free to tear that the shreds. Leland McInnes 00:12, 29 January 2006 (UTC)

I've copied an extended version of this suggestion to the main page, including a description of how to format suitably complex mathematical algorithms (following the standard conventions in math for such algorithms). Perhaps we should get some involvement from Wikipedia:WikiProject_Mathematics on getting this more formalised. Further ideas and suggestions are most welcome. Leland McInnes 04:29, 29 January 2006 (UTC)

As a side note we might want to in general stick to structures that have an "obvious" one-to-one mapping to features in most programming languages: good things would be say, using indexed lists as opposed to pointer/refrences (like C) or a loop with a conditional as opposed to list comprehensions (like Haskell or Python). It might be beneficial to define to formally enough so one could write a program to produce pretty good code in a given language from the pseudo-code. --NotQuiteEXPComplete 23:49, 4 May 2006 (UTC)

[edit] Assignment operator

Traditionally, academic pseudocode has used := for assignment (and that's likely to be the case for sources we use); shouldn't we stick with that for consistency? --bmills 17:46, 11 February 2006 (UTC)

I've seen both := and ← used in academic pseudocode. Personally, I'm ambivalent as to which actually gets used. These are meant to be "guidelines" anyway, rather than hard mandates. Given that they are "guidelines", perhaps it would be better if these guidelines stated that either version is acceptable. Leland? Ruud? --Allan McInnes (talk) 17:57, 11 February 2006 (UTC)

Makes sense to me to state that either is acceptable. I certainly agree that both tend to get used. I'm a mathematician so I generally see more of ← so I went with that. I'll amend the page to reflect either is acceptable. Leland McInnes 22:57, 14 February 2006 (UTC)

I personally prefer ← over := and this is also the notation used in TAoCP and Introduction to Algorithms. I'd also prefer some cosistency among the algorithms, but I also know that this is most likely not going to happen. —Ruud 23:07, 14 February 2006 (UTC)

I like ← more as well, not least because it isn't a composite of two characters. If we could muster some level of , if not consensus, at least plurality then perhaps we could note that ← is the preferred option, but that := is "acceptable". In the end it's a matter of what we can actually find support for with a minimum of pointless arguments. The looser the guidelines the less arguments, but the more varied the resulting pseudocode. I would happily support a preference for ← - any other takers? Leland McInnes 23:19, 14 February 2006 (UTC)

For being slightly more language neutral and simply looking better on my screen I would be willing to claim that ← is preferred over :=. —Ruud 23:28, 14 February 2006 (UTC)

It does look a little nicer and resembles fewer real-world languages, but it doesn't match very well with the old-style keywordy pseudocode we've got so far. Most of our pseudocode resembles academic papers from 1965-1985, which is when := was most heavily used due to its easy representation in ASCII and other character encodings. --bmills 03:13, 15 February 2006 (UTC)

Please feel free to suggest a more modern less keyword driven pseudocode - things are far from written in stone. I went with something resembling Wikicode, with a few variations for "readability" and "genericity" where I felt appropriate (like eliminating curly brace block delimiting), as a best first guess. Improvements are more than welcome. Leland McInnes 04:46, 15 February 2006 (UTC)

[edit] And/Or

If we're going with "proper mathematical symbols wherever possible" for algorithm descriptions, shouldn't and and or really be rendered as ∧ and ∨? Note that I'm not opposed to using and and or if it leads to more readable algorithms. Just questioning how consistent it is with the guideline we have, as stated — I'd be open to altering the wording of the guideline (e.g. to simply recommend the use of the symbols in the table, whatever they may be). --Allan McInnes 17:13, 2 February 2006 (UTC)

I'm not sure about this on, I think and is more readable in an if-statement, but ∧ in an boolean assignment. And we propably also need a bitwise-and which people should be able to recognize without reading this page. —Ruud 17:19, 2 February 2006 (UTC)

Perhaps the right way to go is and and bitwise-and (as well as things like exclusive-or). That should be readily understandable to anyone without reference to this page. But let's wait and see what some of the other people working on this have to say first. --Allan McInnes 17:27, 2 February 2006 (UTC)

I think that would be a good idea, as programmers without any formal education are likely not to recognize symbols like ⊕ and ∧. —Ruud 17:38, 2 February 2006 (UTC)

[edit] Both/And

• JA: Fashions come and go. I recall a time when everybody felt like "real logo-maths don't use words", then it became hip, er, cool, er, PC to write out even immoderately pleonasty things like "if and only if". I think if we follow a rule of "what helps a reader" (WHAR? -- what they did to me in CS with their acronymania is another story), then we'll probably interweave both, hieroglyphs suitably cartouched, and laxer lingo in line. But I'd leave it to the category of friendly advice, and not make an auto(matic)-da-fe out of it. 'Cause you know, "Nobody Expects The Spamish Inquisition" (NETSI). Jon Awbrey 17:44, 2 February 2006 (UTC)

Understood. These guidelines are meant as just that: guidelines. Not a mandated style. Just something to help achieve some consistency, and to provide some tips for people who are creating a new article. The Wikicode debacle debate made it pretty clear (to me at least) that trying to mandate a standard is doomed failure. --Allan McInnes 19:41, 2 February 2006 (UTC)

[edit] Introduction Example

The project page suggests

It is a good idea to also have a basic introduction to the topic, with reduced technical detail and suitable for a high school student or a first-year undergraduate, as appropriate. The basic introduction should give the reader sufficient understanding of the topic to grasp how and where the concept might be used, and a reasonable ability to judge when it might be applicable to a specific problem. For example,

And after much hunting I have failed to find any articles that have a suitable introduction to be provided as an example. There may well be one out there, but it is certainly hard to find. I suggest that it would be beneficial to the project to choose a suitable article (preferrably one we wish to try to rapidly move toard featured article status) and simply write an introduction. With enough hands focused on the task surely something suitable can be realtively quickly hammered out. Does anyone have any candidate articles? Curry-Howard could possibly work, and Topos already has an introduction, just not one suitable for high school students (though it could be made so with a little work). Any other suggestions? Leland McInnes 01:13, 3 February 2006 (UTC)

That particular suggestion was as much wishful thinking on my part as anything else. I suspect some topics are just going to be too hard to boil down to the high-school level. The best we'll be able to do is copious wikilinks to the terms and concepts we're using. And no, I don't have any suggestions for examples, although I agree that Curry-Howard is quite good, and I think that Finite state machine does a pretty reasonable job. --Allan McInnes 02:41, 3 February 2006 (UTC)

Perhaps it would also be useful, in some cases, to have introductory analogies or the problems which inspired a specific solution. For example, the dining philosophers problem should be contained in (or at least breifly explained in) the article on semaphores. Right now is it only linked to from the article. Perhaps the solution should be phrased in terms of the analogy as well. I suppose that my suggestion boils down to saying that when stating solutions, we should make some effort to state the problem as well, both in formal terms and in terms of some analogy. Any thoughts? --NotQuiteEXPComplete 13:44, 14 July 2006 (UTC)

[edit] Functional pseudocode

The proposed pseudocode looks good, but what about functional pseudocode? There's an awful lot of bad Scheme code in Wikipedia, quite a bit of Haskell (which is actually fairly readable for a beginner), a bit of ML, and a lot of lambda calculus. Just sticking to lambda calculus works well for "pure" functional code, but a lot of the functional pseudocode uses algebraic data types with pattern matching, which don't exist in pure lambda calculus. --bmills 17:43, 11 February 2006 (UTC)

Good question! During the Wikicode debates I believe that they decided that "imperative pseudocode is more understandable". Which may be true, for imperative algorithms :-) But of course some things are better expressed functionally though (trying to describe Okasaki's purely functional data structures using imperative pseduocode would probably be a bit of a stretch). So, what to use? I agree that pure lambda-calculus isn't really feasible. But I'd also prefer not to pick one language (e.g. Haskell or ML): pseudocode is supposed to be language agnostic. There's also the question of lazy vs. strict semantics. I have no idea how to handle that.

With regard to what the pseudocode should look like, I like the look produced by the lambdaTeX Haskell typesetter (that look in turn being based on Okasaki's style of typesetting ML). It's also somewhat consistent with the guidelines we've already laid down for imperative code.

--Allan McInnes (talk) 18:24, 11 February 2006 (UTC)

<haskell-propaganda-mode>Haskell looks pretty much like ML if you don't go too wild with it's more advanced features. My guess would be that it is pretty readable to Lispers and Schemers as well. What about using Haskell, but not using lazy-evaluation unless explicitly stated, avoiding the more obscure functions and operators from the Prelude and writing λx.x instead of \x->x?</haskell-propaganda-mode> —Ruud 18:39, 11 February 2006 (UTC)

That's pretty much been my standard; sounds fine. I think it's best to lean on the Haskell/ML family, as there's a great deal of ignore-on-sight prejudice towards Lisp syntax. To the unacquainted, Haskell/ML definitions are also a lot clearer than Lisp definitions. --Mgreenbe 18:47, 11 February 2006 (UTC)

I agree with the above. Plus, Haskell was invented to provide a kind of lingua franca for FP, so it makes sense to lean on something Haskellish. I also like the idea of using λx.x instead of \x->x. Beyond that, please take a look at the way lambdaTeX (mentioned above as well) typesets things like type signatures and the like. --Allan McInnes (talk) 18:56, 11 February 2006 (UTC)

The pseudcode guidelines were meant to be fairly loose and flexible, and just guidelines anyway. I think it's reasoanable to be fairly free in terms of what you do beyond the rough structures the guidelines lay out - for instance you'll note that there is no mention of types at all. If you don't feel you can extend the existing pseudocode guideline into something suitable for functional algorithms, feel free to suggest a different set of guidelines for functional code, hopefully hewing to the same sort of style/flavour as what currently exists. Leland McInnes 19:41, 11 February 2006 (UTC)

After taking another look at the existing pseudocode guidelines, I couldn't quite see how a Haskellish syntax would fit in there. So I decided to try something else. I've added a proposed guideline for pattern-matched functions to the MoS. It follows the style we've already established much more closely than Haskell does. If it looks ok to everyone here, maybe we can give some thought to how we might translate other common FP constructs into this style. If everyone hates it (I'm willing to concede that it's a little clumsier than Haskell) maybe we should consider revisiting the guidelines for imperative code too. I'd prefer if we could come up with a single "style", since it's entirely possible that there'll be some pages that mix imperative and functional code. Come to think of it, how are we going to deal with object-oriented code or logic code? Might as well cover all the paradigms... --Allan McInnes (talk) 05:50, 12 February 2006 (UTC)

It looks okay to me (though some optional delimter to mark the end of a patterns code block might be nice). In general, however, I a loathe to getting into too much detail in guidelines on this and the particulars of various programming paradigms. In principle the pseudocode guidelines are for documenting algorithms, and if you method of expressing an algorithm requires the use of various constructs idiosyncratic or idiomatic to particular programming paradigms then I would suggest that you should either

1. Consider describing the algorithm at a higher level that doesn't require such constructs
2. Consider a how such constructs can be expressed in a more generic way

For example, with pattern matching, it might be easier to have, for example,

function factorial is
    Input: n, a non-negative integer
    Output: the integer value of n!
    if n = 0 then
        return 1
    else
        return n × factorial(n−1)

which, while a little more clumsy, is probably clear to a much wider audience. Of course not everything will work this way, and it may well occur that you need special constructs. In that case I think some sort of guideline with regard to "do the obvious thing" ought to be enough. For instance, if you had to use pattern matching I think the current suggestion is a perfectly good example of "do the obvious thing", and while I can think of other variations they will be, for the most part, sufficiently similar that it won't matter. Similarly if you need to use OO then anything along the lines of

class class_name is
    variable foo
    variable bar

    method method_name is
        code block
    end method
end class

will most likely be fine, where "variable" and "method" can be "var", "property", "member", or "data" etc., and "procedure", or "function" etc., without any real loss. I think once you try and codify too many particulars such as this you start digging yourself into the Wikicode hole. I would rather not go there. Leland McInnes 22:46, 12 February 2006 (UTC)

The vertical bars delimit the start of a new pattern (similar to the way ML does things. I'm all for "doing the obviosu thing" — I just threw the example out there to start some conversation. --Allan McInnes (talk) 03:54, 13 February 2006 (UTC)

I've tried to include some explicit instructions to avoid idiomatic pseudocode where possible and "do the obvious thing" where it isn't. For now I've removed the pattern match example - it didn't fit with the guidelines I added. Don't take that as a rejection of it, simply as me being unable to figure out how to elegantly include it. It seemed very natural and in line with the current style to me. Perhaps we can have some "general suggestions" regarding idiomatic code outlining how to do pattern matching, types, algebraic types, classes etc. though I would prefer to separate that off somehow into more of a "suggested examples" rather than clutter up the guidelines themselves. Leland McInnes 04:54, 13 February 2006 (UTC)

Sure, that's fine with me. --Allan McInnes (talk) 05:16, 13 February 2006 (UTC)

I've started a page of "suggested examples" as a userpage (thus not conferring any authority to it) so we can at least have a resource for ideas about how to implement various idiomatic structures and techniques in line with the currently defined general style. Please stop by User:Leland_McInnes/Pseudocode_examples and feel free to add, edit, or otherwise fix and extend the examples there. Leland McInnes 03:01, 14 February 2006 (UTC)

[edit] <pre> and <code>

I think that <code> should be used instead of (or in addition to) <pre> for code in articles. That is, after all, what that tag was intended for, and we should be using our markup to actually mark up the document.

Here's an

inline pre block

and an inline code block. Note that the code block actually works inline, whereas the pre doesn't.

However, Wikipedia's engine hates code blocks by themselves.

int main (void) {

   printf("hello world\n");
   return 0;

}

There are two possible solutions:

• putting pre blocks inside code blocks:

int main(void)
{
    printf("hello, world\n");
    return 0;
}

• starting all code with at least one leading space:

int main (void)
{
    printf("hello world\n");
    return 0;
}

If someone could improve the engine, I think it would be best to just use <code>; otherwise, I think we should use pre blocks within code blocks. Regardless, we should ensure that all code (inline or in block form) is enclosed in <code> tags. That way we can do the following:

Consider the main function for the "hello world" program:

int main(void)
{
    printf("hello, world\n");
    return 0;
}

Note the use of printf to display the output.

--bmills 18:02, 11 February 2006 (UTC)

You should write inline code with <code> and outline code like this (doesn't require code or pre)

id :: a -> a
id x = x

—Ruud 18:27, 11 February 2006 (UTC)

The problem you're running into there is fundamental to HTML, not just an issue with MediaWiki. Unfortunately, HTML doesn't fully support semantic markup. I'm not sure what the best solution is. --Allan McInnes (talk) 18:29, 11 February 2006 (UTC)

I'm more concerned with making edits easier, and with making the pages forward-compatible — if we use the <code> tag for all code, it doesn't cause any harm, and it does make it easier for screen-readers and other HTML-processing software to figure out what is code and what isn't. Also works well on the off chance that the user has custom CSS set for code.

While HTML isn't fully semantic, it seems to me that we should apply as much semantic information as we can; in this case, that means tagging our code as code. I'm going to go ahead and add something to that effect since this is a pretty volatile draft; if anyone feels strongly otherwise do feel free to remove it. --bmills 03:20, 15 February 2006 (UTC)

I created two templates {{algorithm-begin}} an {{algorithm-end}} for use in the alorithm article. Is this the kind of semantic information you are reffering to? (Although the templates also add some visual information.) —Ruud 17:01, 15 February 2006 (UTC)

Not really; mainly I mean that definition lists should use definition list markup, <table> should only be used for tables, etc. Since there's an HTML tag for code, we should use it. --bmills 17:39, 15 February 2006 (UTC)

I don't think I follow you here, you shouldn't use <b> for bold or <table> for tables, MediaWiki markup is not HTML although is does allow a limited set of it. —Ruud 17:49, 15 February 2006 (UTC)

Right, but MediaWiki markup compiles down to appropriate HTML; since there isn't any MediaWiki markup for code, we should use the HTML for it. --bmills 17:55, 15 February 2006 (UTC)

Not for inline code, no. But there is for

outline code

so I guess you are talking about the first? —Ruud 18:03, 15 February 2006 (UTC)

[edit] Concrete Implementations of Algorithms

Sometimes it is beneficial to have a concrete implementation for explanatory purposes, but generally pseudocode is better. This, of course, doesn't stop people producing implementations in their language of choice and adding them to the page. Just look at Quicksort implementations to see how out of hand that can get. The logical place for such a repository of implementations is on Wikisource, and we really ought to be encouraging people to take their implementations there - because certainly a code repository of implementations of each algorithm is certainly of value. On that front I've begin to think that maybe the right way to go is to create a template for algorithms that links to a corresponding page on Wikisource as the place to find implementations, and start attaching the template to algorithm pages. Sure the Wikisource page in question may not exist yet, but a suitably worded template can imply that it's the place to look for (and put) implementations, but not to expect to necessarily find them. Something like "Concrete implementations in various languages, if any have been submitted, can be found at link". Is it worth trying to make such a template? Comments? Suggestions? Leland McInnes 04:42, 15 February 2006 (UTC)

I agree that an encyclopedia is a poor place to put to implementations (as you may have seen from my recent edits). As such, I think we should discourage outright links to implementations; to do otherwise will only provide people with the idea that links to implementations are acceptable in general, and thereby encourage linkspam from people adding their favorite other implementations. If we want to point out the existence of materials on Wikisource, we can always use Template:wikisource, which has that nice "sister project" look rather than the "link to some other page" look.

However, my reading of Wikisource's goals is that it's mainly a repository for copies of public-domain and GFDL texts, not source code. I don't think we should even be promoting it as a repository for code; that's what SourceForge is for, though it's not a WikiMedia project. --bmills 05:05, 15 February 2006 (UTC)

How about just using

{{Template:Wikisourcehas|implementations of this algorithm|'''''[[wikisource:Special:Search/{{PAGENAME}}|{{PAGENAME}}]]'''''}}

whenever unnecessary implementations are added, and simply shuffling off implementations there. I admit that Wikisource may not be an ideal place for a code repository - but it is certainly a better one than Wikipedia. Leland McInnes 05:23, 15 February 2006 (UTC)

WP:WWIN clarifies the purpose of WikiSource explicitly (my emphasis): "Complete copies of primary sources (but not mathematical tables, astronomical tables, or source code) should go into Wikisource." Therefore, we should not encourage source code to go there. --bmills 05:25, 15 February 2006 (UTC)

Hmm... On the other hand, [1] seems to indicate otherwise. But it still isn't supposed to contain original writings, and I haven't actually seen any code there. --bmills 05:29, 15 February 2006 (UTC)

It looks as if there isn't a simple answer for this. How about we just follow the Quicksort implementations example and divert to a different Wikipedia page? Still far from ideal. It is useful information, and it ought to be somewhere - the question is where is the right place for it? At this point I'm quite open to suggestions. Leland McInnes 05:40, 15 February 2006 (UTC)

It may be useful, but it's not encyclopedic; it belongs in a more general repository of useful information (a.k.a. the World Wide Web!) rather than Wikipedia in particular, which aims to be an encyclopedia. Maybe it could go to SourceForge or the Great Compiler Shootout or something. Regardless, I intend to put Quicksort implementations up for deletion soon (we'll see where that goes). --bmills 05:52, 15 February 2006 (UTC)

I did hear something about Wikisource (planning on) deleting a whole lot of source code a few months ago. Yet one some other page I read host source code (yet, this may only be primary source code, if there is such a thing?) Could be interesting to see what happends when you place Quicksort implementations on AfD though. —Ruud 11:15, 15 February 2006 (UTC)

I do remember seeing code on Wikisource before (including a few quicksort implementations). But a quick search now shows that they appear to have purged many of those pages. I agree with bmills that lists of implementations are unencyclopedic (I early brought this up at Talk:Quicksort implementations, but was persuaded by Deco that it was a reasonable defensive measure). As you say, it'll be interesting to see where the AfD goes. --Allan McInnes (talk) 18:27, 15 February 2006 (UTC)

[edit] Code Samples

Given the line being taken on inclusion of source code (which I generally agree with) I think perhaps we should actually have some clear an explicit guidelines as to exactly when code samples are and are not acceptable. At the moment the explanation is fairly vague, and I think some firm policy would be beneficial. Clearly code to demonstrate the look of a language, for example on the various language articles, is justified. Equally language specific features, or, at least, features that aren't easily translatable into easily understood generic pseudocode, are also reasonable. Are there any other cases where code samples are acceptable? I'd like to get something resembling a firm policy hammered out reasonably efficiently. Leland McInnes 22:25, 15 February 2006 (UTC)

I'd say don't use real code on articles describing algorithms, but it may be helpful in articles describing programming constructs. —Ruud 22:46, 15 February 2006 (UTC)

What kind of constructs did you have in mind? I could see it making sense for language-specific constructs. But illustrating a general for-loop doesn't seem like it would require an actual implementation. --Allan McInnes (talk) 23:04, 15 February 2006 (UTC)

Ok, point taken. I suspect there might be situations (don't ask me to name them now :) in articles on programming where you might want use some real code, so having a general policy against it might not be most sensible to have. —Ruud 23:28, 15 February 2006 (UTC)

Algebraic data types don't lend themselves well to pseudocode, since the pseudocode ends up being essentially ML or Haskell. I think the main idea is that if actual source is used, it needs to be intelligible to people who don't know the particular language. --bmills 03:49, 16 February 2006 (UTC)

I think the point is that while the particular pseudocode dealing with algebraic data types may be indistinguishable from Haskell of ML, that's not really sufficient reason to put an entire example in Haskell or ML. If it's only code that's indistinguishable from Haskell then the entire example is sufficiently generic that once can hardly say that is necessarily Haskell, and if there is other code involved in the example then I don't see any necessity to make that extra code language specific. Probably I am simply lacking in imagination as to necessity. Could you could give me an example of something that is clearly Haskell or ML rather than a generic "any of the above" and needs to be so? Leland McInnes 04:20, 16 February 2006 (UTC)

I'm not sure it's a matter of necessity so much as one of consistency and correctness. With language-specific examples, the example can be tested (and automatically checked for proper syntax and types); with pseudocode, the example cannot be executed unless the pseudocode can be executed (and then it's not so "pseudo", now is it?). There's something to be said for mechanical validation. --bmills 05:07, 16 February 2006 (UTC)

This gets into the interesting debate of verifiability of pseudocode. How about we compromise with: if most sources/references only provide a language specific example, then code is fine. If there are sources/references with language neutral or pseudocode presentations then those should be preferred. Psuedocode should be verifiable against the source. Leland McInnes 06:21, 16 February 2006 (UTC)

A very good point: if a reliable pseudocode source can be found, such as the original paper or a variant, use that. I volunteer to be an ACM lackey for nonmembers. --Mgreenbe 11:57, 16 February 2006 (UTC)

That sounds good to me. Pseudocode is clearly best if it can be verified; actual code samples are allowable if they are clear and concise and add to the encyclopedic content of the article. --bmills 14:16, 16 February 2006 (UTC)

I think that sounds like a reasonable position to take. I think the key point is that any algorithms or code must be traceable to a reference. I too can act as an ACM lackey for nonmembers. --Allan McInnes (talk) 19:01, 16 February 2006 (UTC)

Rudy, I take the challenge! The chief utility of code samples is to serve as a grounding, usually for one of two reasons:

1. Showing concrete errors (e.g. buffer overflows) under fixed semantics (e.g. pointers in the C-family). What is the pseudocode for a NULL-dereference?
2. Clarifying complicated/unique programming-language ideas (e.g. monads in functional programming). Any notation we choose which is not Miranda/Haskell/Clean/... is either misleading, too verbose, or both.

Representative code samples in programming-language articles are also helpful, where "representative" means characterizing the syntax and style. "Hello world" programs do not fall into this category. --Mgreenbe 01:45, 16 February 2006 (UTC)

Sounds like decent guidelines to me. Effectively it amounts to

1. In concrete language or implementation specific discussions.
2. When generic pseudocode is inadequate to accurately express the concept.

though I'm sure much better phrasing could be arranged. Leland McInnes 02:46, 16 February 2006 (UTC)

I feel guidelines only benefit from ambiguity and example-based reasoning. So I would propose the following:

• Include actual code only when it is absolutely necessary; pseudocode is preferable.

Examples of cases of inclusion and exclusion would be: language pages (abstracting the syntax is only confusing, so use code), complicated or abstract ideas (a fixed semantics helps, e.g. monads or buffer overflows), and algorithm pages (not absolutely necessary; explain the properties of unique implementations in pseudocode or prose). --Mgreenbe 11:57, 16 February 2006 (UTC)

Hmm... That may be more restrictive than necessary. How about:

• Include actual code in an article only when it significantly clarifies existing prose or pseudocode.

That definitely includes pages about languages and complicated algorithms (which should have a prose description anyway). A point I added the other day should specifically exclude pages like Quicksort implementations:

• Multiple source code implementations are not appropriate unless they contrast specific aspects of the code and that contrast is important to the encyclopedic content of the article. If possible, accentuate differences by providing the alternate implementation in the same language as the original.

(That point is already in the article.) --bmills 19:29, 16 February 2006 (UTC)