Pointless Programming Reference Notes

Style Guide

The style guide provides general formats for contributing solutions.

Code Notation

Each solution can have a number of parts, all of which are optional.

Code (Input/Output)

a = 42

a

>>> 42

The code field should contain only code that should be run and its output.  Input should be written as if you were writing code in an editor.  Output should be preceded by three > symbols and a space “>>> “.

You can have as many inputs and outputs as you need, however remember that you can also add a new entry and a separate example should go in a new entry.  For example this is a valid entry...

count = 0

for i in range(3):

  count += 1

  print i

>>> 0

>>> 1

>>> 2

count

>>> 3

Consecutive output lines as above are equivalent to the string “0\n1\n2\n” being printed to stdout.  It is important that these conventions be used, as this document is meant to auto-test itself to alert its maintainers when features have become depreciated/unsupported in new versions of a language.

Input should be kept short (see Long Lines) and use recommended naming conventions (see Naming Conventions).

Long Lines

Long lines will be wrapped and therefore should be avoided if at all possible (I realize this may not be possible for some languages *cough* Java *cough*).  Right now the PLR wraps lines at 60 characters, but do not rely on this!  At some point in the future the PLR may be displayed in a more ‘fluid’ layout that automatically re-sizes each column based on page width.  There will, at some point, be a minimum character length that you can rely on and it will probably be somewhere around 60 characters, however this number has not been formalized yet, so try to keep lines as short as possible.

In cases where it is not possible to use a line of less than the minimum characters, try to use the language’s line continuation character (if present).

Comments

The comment section describes the solution in general.  This section should be used to display any notes on the solution or the task’s applicability to the language.

Links

Wherever possible, include links to relevant, quality documentation on the solution.  

Variable Naming

This section is under review!  Nothing here should be taken as the right way to do it.  For now.

It is important to have consistent naming throughout the PPR.  For one it reduces the burden on the reader of figuring out the differences between languages.  Secondly, using consistent naming will allow the viewer to choose their preferred style of naming.

Names should not differ from each other based solely on case as some languages are not case-sensitive.  

Names should always start with a letter.  

Loop counters should always be ii, jj, kk.  There is simply no easy way to do a search/replace on i, j or k.  If you don't like ii, jj, kk then change the settings on the viewer.

Entries

When writing the first entry, code for clarity and simplicity.  Ideally, code in the first entry should be somewhat understandable to someone with little to no knowledge of programming.  Multiple entries are allowed per task so you can put more efficient/idiomatic/etc versions there.

Terminology

Category:  A very general grouping of ideas.

Section:  A general grouping of related concepts.

Sub-Section:  Sections are divided into sub-sections to make reading and searching the PPR easier.

Tasks:  Each task describes a single action.  Tasks should not be grouped, use the sub-sections for that instead.  For instance there should not be a task about splitting and joining a string.  Rather there should be two tasks; splitting a string and joining a string.  In many cases this distinction can be blurry as some languages combine operations into a single function.  In these cases you should use your best judgement.  

Language:  A placeholder for entries.  Each language can have multiple entries for a single task.

Entry:  An entry is the most basic element in the PPR.  An entry is composed of comments, code and/or links.

Templates

Templates provide a way to reduce both the burden and errors when entering new submissions.  Some languages require one or more lines of code that do not necessarily pertain to the solution, to produce working code.  This is necessary for two reasons, the first being people who are cutting and pasting code from the PPR and the second is the testing program that alerts the maintainers when the PPR has become out of date.

For instance a language like C requires at least three lines of code in every solution that do not pertain to the problem, demonstrated as:

#include <stdio.h>

int main() {

  printf(“hello world”); /* This is the only relevant line */

}

In this scenario there is only one line of code that is necessary to show the concept of printing to the screen.  However for this snippet to run when copy/pasted or tested it requires the whole block of code.

Templates should be shown in every solution by default.  The rational behind this is that people new to programming will easily overlook this and experienced users will likely figure out how to turn it off.

Templates make a language look more verbose than it actually is.  Consider the above example, printf(“Hello World”) is three characters longer than Python’s print “Hello World”.  The template adds 29 characters to this.  However real world programs are often hundreds of lines long, making the addition of the template code add less than a character per line.  

FAQ

When can I start adding my own solutions?

Hopefully soon.  I’m working on a wiki style entry system for the general public.  Mostly I’m trying to work around the various limitations of my current hosting solution.  Until I figure this out the PPR will remain read-only.  For the moment, you may contribute by emailing me your solutions.

Won’t this encourage programmers to continue doing things as they would have in their old language instead of embracing the idioms of the new language?

Short answer, I hope not.  

What is the purpose of this?

To help someone learn a new language.

To compare how different languages accomplish the same tasks.

To help people that switch languages often and forget some of the tiny details.

But this section is not relevant to my language!

In some cases entire sections will be completely irrelevant.  For instance a section on pointers would not be relevant to Python, and a section on reading and writing files is not relevant to Javascript.  Where this happens I will attempt to make some kind of note saying not relevant.

Just because it's bad practice doesn't mean it doesn't belong here!

A certain style of programming or particular case may not be accepted practice in all languages.  For example you should not rely on tail-call optimization in C (though some compilers do it).  This does not, however, mean that instructions on how to do recursive tail-calls should be left out of the C section.  Rather it means that a note should be put in to explain why it is bad practice.  Note, the absence of a note does not mean that the particular solution is the right way to do it.

Why would you include goto here!  It's never a good idea to use goto!

This document is not a place to have flame wars about whether a programming practice is good or not.  There's almost always a legitimate use of every language feature.  Where not noted the burden of determining a given solution's applicability is left to the programmer.

Why did you use _____ naming convention?

Wherever possible all non-language specific things are exactly the same throughout the document.  One reason for this is simplicity.  The burden of figuring out the differences between languages is lessened if consistent names are given to variables and function names.  The second reason is formatting.  If consistent names are used the viewer can choose their preferred naming convention.  For instance the viewer may want to see variables named a_string instead of aString.

What naming conventions should I use?

Short answer; see the Style Guide.

That's a good question and I'm trying to figure that out as I go along.  One of the goals of this document is to have the code displayed in whatever manner the viewer chooses.  This means that variable naming is also configurable.  If a user does not like "aString" for their string variables they should be able to change it to "string1" or whatever other convention they choose.  This is only possible if there is consistent variable naming throughout the whole document.

One of the other challenges with naming is using names that can be understood and differentiated in all languages.  For example, a common Python practice is to name classes with an uppercase like “String” and instances of that class with lowercase like: “string = String(“hello”)”.  This presents a problem for languages like Common Lisp that are not case-sensitive.

TODO

Insert Links to Documentation on each feature in each language.

At any chance expand the English Language section.

The English Language should eventually become a through description of the task and its methods of solution.  The first paragraph should be a one or two line description of the task.  Afterward should follow a detailed description.  After that can follow a description of the algorithms or methods used to solve the task.  

The code section should be an English description of the algorithms used to solve the problem in other languages.  And the link section should provide links to general overviews of the task.

Make variable names more consistent and explanatory.

For example there should not be variable a, aList and testList in the List section, these should be replaced by a single explanatory variable such as aList.

Organize Sections!

There should be a coherent flow to the document.  A section on functions should not be between sections on data structures).

XML Based Implementation

A new implementation of the Pointless Programming Language Reference is underway!  See this blog post for more details.

Coming References...

Pointless Programming Language Reference

Pointless Programming GUI Toolkit Reference

Pointless Programming Markdown Reference

  html,

Pointless Programming Database Schema Reference

  JSON, XML, etc

Pointless Programming Algorithm Reference

© Jack Trades, 2008, 2009, 2010, 2011