Posts should ideally be formatted so that they could stand as an article on their own
A good PPCG post is, from my point of view, something of a miniature article on its own. The heading for a post should therefore be a top-level heading (i.e. one #). I use two # signs for secondary headings lower down, because they aren't the headings for my post as a whole.
It's probably a bad idea to make a post format mandatory, at least in terms of deleting posts for not complying with the format (although I wouldn't necessarily be opposed to posts being edited into a consistent format, if it's well thought-out). That said, though, I've kind-of become notorious for the rate at which I can gain reputation, and a decent part of that is that I try to make my posts well-formatted and well-explained, so that people are more likely to read, enjoy, and thus upvote them. As such, you could definitely do worse than formatting posts the way I do ;-)
The header line of the post can potentially need to contain quite a bit of information. Here are the header line contents I'm aware of, and how I format them:
- The language in which the program is written (obviously). This helps people check to see if their solution has already been beaten or equalled in the same language, and if so, if the algorithm is too similar to make a posting theirs interesting. This comes at the start of the line.
- Language implementation or version. We define languages by their implementation here; thus, two different implementations of a language are actually different languages. Often, that doesn't matter, and we can safely assume a relatively recent, widely accessible version of the language. If there are many competing implementations, though, or if the submission relies on implementation-dependent behaviour, it's worth stating a specific version of the language. I put this in parentheses, e.g. Perl (5.10) or INTERCAL (C-INTERCAL).
- Any other dependencies of the submission. If the submission needs a particular executable to be installed (say, the interpreter for a different language), or a particular nonstandard library, or whatever, it's worth mentioning that in the title, as a) it's arguably part of the language, and b) it often makes a big difference to the way that the answer works. I use a + sign for this, e.g. Bash + Jelly + Graphviz (an actual submission!). This also comes in handy in polyglots, which require multiple languages installed to do their polyglotty thing.
- Score. This is normally a byte count, but not always (e.g. in a code-challenge, the scoring is typically different). Listing the byte count can be useful even in challenges with weird scoring, because it's often relevant to either the scoring or validity in one way or another.
- Older scores are worth showing, crossed out. This hints to people that they can look into the history of the post to see the evolution of the submission, and can help to explain parts of the explanation that pertain to the wrong version of the program.
- If the submission incurs bonuses or penalties, it's also worth including those separately, so that people who count the bytes themselves can understand where the score comes from. I use a format like bytes + penalties = score (seeing as I frequently golf in Perl, I often end up incurring a couple of bytes in penalties for weird command-line options).
- Finally, if there's information that could potentially invalidate the submission, that's worth including in the title to avoid arguments about who's won (for the people who care about having a specific winner). Many people say "noncompeting" here, but I dislike that because a) it's pre-empting decisions by other people on what's legal and what isn't, and b) it doesn't explain why the post is disallowed from winning. So I put a short explanation here, typically "language postdates challenge", as most other conditions that make a post noncompetitive also disallow you from posting the post at all. (The second most common is "possibly invalid?", in situations where there's reasonable doubt about whether the program complies with the specification or not; in such cases, you leave the post up because there's a reasonable chance that it does, but you put the warning on so that people are at least aware of the dispute.)
And for completeness, here's the sort of information you need in the rest of the post:
- The program itself (or instructions to reproduce it if it wouldn't fit into a post for some reason, e.g. nonprintable characters, a bytecount which has more digits than a typical program has commands, etc.). This is obviously required for people to be able to evaluate the submission.
- A link for executing the program online; not mandatory, but it makes the submission better.
- An explanation of how the program complies with the rules (choices made in answering the question, the source of any bonuses or penalties, I/O formats, etc.).
- An explanation of the program itself. In relatively readable languages, this can just be an indented and commented version. If the language is less readable, you may need to epxlain how it works, character by character.
Example
A typical post would look something like this, for me:
# Language + library (implementation), <s>42</s> 41 + 2 = <s>44</s> 43 bytes <!-- language-all: lang-whatever --> (if SE has highlighting for the language) program goes here; this program is golfed [Link to test the program online](http://example.com) Run with `-ok` (2 byte penalty). ## Explanation This program works in the following way, using this algorithm. It's actually fairly frustrating; it could be 5 bytes shorter if only the implementation didn't have a bug. Use of the `-ok` option, despite the penalty it incurs, makes the I/O much easier and is well worth the cost. program goes here # explanation of what it means for the program to go here this program is golfed # explanation of what it means to be golfed
That looks like this:
Language + library (implementation), 42 41 + 2 = 44 43 bytes
program goes here; this program is golfed
Link to test the program online
Run with -ok (2 byte penalty).
Explanation
This program works in the following way, using this algorithm. It's actually fairly frustrating; it could be 5 bytes shorter if only the implementation didn't have a bug. Use of the -ok option, despite the penalty it incurs, makes the I/O much easier and is well worth the cost.
program goes here # explanation of what it means for the program to go here this program is golfed # explanation of what it means to be golfed