clc-wiki:Policies - clc-wiki

This page is intended to reflect the consensus of those involved with the wiki, those interested in becoming involved, and those active in the community based around comp.lang.c who choose to associate the two, as well as to simply document a few evolved conventions. The page has been drafted without a lot of consultation though, so if you see something objectionable or less than clear, please make a note of it on the talk page.

Policies are to be considered firmer than conventions and deviation from policy to be viewed less favourably than deviation from convention.

Replication and backup/code availability

Policy: Configuration details and the exact software running this site will be publically available

This is already occurring at Planning:Wiki customisation.

Policy: Database backup availability (still to write)

Still to write...

Personal information

Policy: Registered email addresses will not knowingly be made overtly public or available to spammers

No email address registered with a user account will be publicly displayed or made directly accessible anywhere on the wiki.

Email addresses are stored as part of the wiki's database backup file. These backups are currently being accessed by only one person other than the site administrator, but in future more people may access them. Anyone with access to backups must agree not to make public or otherwise distribute the email addresses in the backup file prior to being given access. Additionally anyone with access to backups must agree not to use any of the registered email addresses for direct email contact unless that email address is already a contact or was also legitimately available elsewhere.

Licencing and copyright

Project:Copyrights is a less comprehensive version of this section.

Policy: Contributed content is in general licenced under the GNU Free Documentation License 1.2 (GFDL)

Per heading.

Policy: Contributed code enters the public domain unless an alternate GFDL-compatible licence is specified at time of contribution

Contributed code enters the public domain unless the contributor specifies otherwise at time of contribution - i.e. in a following summary line as described below. Any alternative licence must be compatible with or equal to the GFDL.

Policy: Don't contribute code or other content that you have no right to licence appropriately

Contributers of code or other content must have the right to licence it as described above. In general, this is when the content is your own, is in the public domain or is under a licence compatible with the GFDL where the contributer specifies that the content is being contributed under that compatible licence.

Policy: Respect the work of others

Behave ethically with respect to other people's work when contributing code or other content to this wiki. "Ethically" is as defined by consensus, which might vary as this wiki's active contributing community varies, so be conservative. Determination of consensus might also take into account the opinions of regular or noted contributers to comp.lang.c who haven't directly contributed to this wiki.

If you follow these guidelines for original contributions you shouldn't encounter problems:

write all code or other content yourself, without copying and pasting from anywhere
refer to nothing but the Standard and its rationale, and optionally descriptions of algorithms from a source that you have a legal and ethical right to view (again, be conservative in defining "ethical" here)
avoid contributing code when you've been closely exposed to similar code that you have no right to contribute and when you haven't made a strong effort to avoid unconsciously replicating parts of the other code - both its general structure/algorithm(s) as well as specifics like identifier names and layout
acknowledge inspiration, sources and possible unconscious infringement (see the convention below).

Ethical guidelines applying to non-original contributions are to only contribute within your legal rights and to first seek the author's consent in any case.

Convention: Seek permission or otherwise inform those whose code or other content you legitimately contribute; identify the source, author(s) and details of communication when contributing the content

If you are contributing code or other content to the wiki that you have not written yourself but that you nevertheless have a right to contribute, such as content in the public domain, then first attempt to identify its author(s) and obtain permission, or at least inform the author(s) of your intention to contribute the content. Do not proceed if the author(s) express concern. Prefer that the author contributes the content under a username of his/her/their choosing and indicate this preference in your correspondence. Indicate both the author(s) and the original location of the contributed content both in the edit summary and on the talk page, and include details of any steps that you took to inform or obtain the original author(s)'s permission.

Convention: Disclose all references used whilst writing contributed code or other content of your invention, as well as any possible contamination

If you contribute code or other content of your own devising, describe in the edit summary (if it fits OK) and the talk page (only necessary if you used references beyond the C Standard) any references that you used or were inspired by to write the content, including:

which version(s) and/or drafts of the Standard you used
any books, web pages, ftp sites or other sources that you based all or part of the content or code on. This includes references for pure algorithms as well as references for source code.

If you are aware of previously reading code that you have no right to contribute but that is similar to code that you are contributing, then describe what/where that other code is and any steps that you've taken to avoid infringing its copyright.

C code

This section describes policies and conventions concerning C code embedded within this wiki's pages.

For code review procedures see Project:Code reviews.

Policy: Focus on portable C code and avoid extensions and C++

The focus of this wiki is on portable C code as defined by the C Standard. Non-portable C code and any form of C++ code should be added for incidental demonstration purposes only and should be isolated into as small a snippet as possible. Non-portable code includes common extensions such as those of POSIX, of the GNU C Compiler (gcc) and of Microsoft C implementations.

Convention: Document non-portable dependencies in implementation code

Code written to demonstrate how a standard header or function might portably be implemented should document identifiers that have no portable implementation by prefixing the name with __np. All such identifiers should be added to the Non-Portable Standard Implementation Components page.

Convention: Enclose each block of code within <c></c> tags

Every block of C code in the wiki should be enclosed in <c></c> tags - this provides syntax highlighting, generation of links for keywords and standard functions, and protects against interpretation of any of the code as wiki formatting instructions.

The syntax highlighter will strip a leading empty line from the code block so it's fine to place the opening <c> tag on a single line and start the actual code block on a new line.

[Aside: Other types of code can be highlighted, including the C grammar - as described by the Standard - using <c_grammar></c_grammar>. The <c_grammar></c_grammar> implementation is still under development, but it is safe to use in its current state.]

Convention: C code should be formatted according to K&R style along with other guidelines

Code should be formatted according to K&R style - that used in Kernighan and Ritchie's The C Programming Language. This can be achieved simply by running indent -kr <filename> where <filename is the name of the source file to format and indent is a tool commonly available on Unix-like operating systems. A basic explanation of K&R formatting style is provided at Project:Code style guidelines.

Other formatting guidelines are:

avoid tab characters; indent to four spaces
keep line length moderate - about 80 characters maximum
avoid //-style comments.

Not all current code conforms to this convention but future code should.

Convention: Several other style recommendations apply to C code on this wiki

multiple exit points from a function should generally be avoided, but aren't prohibited e.g. they're fine when a function is very brief and a single-exit would unnecessarily complicate it.

The style article discusses the issue beyond this wiki's guidelines.

Convention: Update the summary line when modifying an existing block of code

If you modify any part of the code (including comments or formatting) within a block of code that has a subsequent summary line, or you modify the type or conformance fields of the summary line, you should:

comment out any existing reviews by enclosing them in  tags
set the later-reviews--"none"-or-empty parameter to "none" (without the double quotes)
append the names of the reviewers whose reviews you have just commented out, as a comma-separated list, to the past-reviewers--no-line-breaks parameter (the template messes up if line breaks are included so avoid them)

If the code does not yet have a summary line, you should add one by copying, pasting and editing the template below.

Convention: Classify each block of code

Each self-contained block of code should be classified as follows, and the choice documented in the summary line as described further down.

Code types

full program: will compile to executable as-is
main program: contains the main() function and will compile to executable as-is when linked with non-standard libraries defined within this wiki
compilable unit: will compile to a library as-is
incomplete unit: has dependencies, such as identifiers using the _np prefix as described previously, but would otherwise compile to a library as-is
complete snippet: will compile when inserted as-is into an appropriate location in other code
incomplete snippet: cannot be made to compile as-is - e.g. because it contains ellipses indicating "fill in appropriate bits here"
complete header: intended as a header file; no dependencies and will compile as-is
incomplete header: intended as a header file; has dependencies, such as identifiers using the _np prefix as described previously, and will not compile as-is

Code whose conformance type as defined below is "broken", because it's a deliberate example of a flawed implementation and is incompilable, should be classified as seems appropriate - e.g. if it would otherwise compile as a full program bar a syntax error, it should be typed as full program.

Conformance types

strictly conforming: A strictly conforming program shall use only those features of the language and library specified in this Standard. It shall not produce output dependent on any unspecified, undefined, or implementation-defined behavior, and shall not exceed any minimum implementation limit. (quoting The Standard, 4#5 - N1124 numbering)
portable in implementation namespace: uses or defines identifiers reserved for the implementation namespace to demonstrate how parts of a Standard C implementation/library can be coded, but is otherwise strictly conforming
non-portable in implementation namespace: uses or defines identifiers reserved for the implementation namespace to demonstrate how parts of a Standard C implementation/library can be coded, and relies on unspecified, implementation-defined or undefined behaviour to function - all assumptions should be documented for this type of code
non-portable: contains code that invokes unspecified, implementation-defined or undefined behaviour (should only be included for demonstration purposes)
broken: contains code with a syntax error or other constraint violation that a compiler must reject (should only be included for demonstration purposes)

C90 and C99: strictly conforming and portable in implementation namespace should be qualified with C90 or C99; C99 should only be indicated if specific features of C99 are relied upon, and those features should be explained alongside the code.

Convention: Use a summary line to describe the block of code that it follows

A summary line should immediately follow each code block, indicating such things as licence, portability, code classification and review status. Templates have been created for this purpose. They are Template:codesummary, Template:passingreview and Template:failingreview.

The rest of this section describes the usage of these templates.

Summary Line Starter

Summary lines can be based on this block of wikitext (as rendered, not as it appears when edited).

{{codesummary |
type= Full program or Main program or Compilable unit or Incomplete unit or Complete snippet or Incomplete snippet or Complete header or Incomplete header |
conformance= strictly conforming {C90 or C99} or portable {C90 or C99} in implementation namespace or non-portable in implementation namespace or non-portable or broken |
licence= public domain or [http://www.gnu.org/copyleft/gpl.html GPL] or other open source licence |
past-reviewers--no-line-breaks= none |
later-reviews--"none"-or-empty= none }}


Notes

the type and conformance fields document the classifications chosen according to the convention described previously
the licence field documents the licence chosen in accordance with the policy described previously
the past-reviewers--no-line-breaks parameter should be updated in accordance with the convention for modifying code as described previously
the later-reviews--"none"-or-empty parameter should be given a value of "none" when no reviews exist, and be left empty when either a passingreview or failingreview follows (the template inserts "current reviews: ")
the parameters for the passingreview template are described at Project:Procedures:Code reviews#Review_types
the parameters for the failingreview template are described at Project:Procedures:Code reviews#Review_components
the pipe symbols (|) are part of the wiki formatting, not a semantic indicator of options
 are comment block delimiters within wikitext in the same way that they are within html
subsequent reviewers should copy and edit one of the commented-out (and hence undisplayed) lines as appropriate

Example 1

The following summary line describes a full program under a BSD-type licence that's strictly conforming to C90 without relying on any C99-specific features. Since its last change it's been twice reviewed, passing one cursory review by Clcer2 and failing the behaviour inspection component of Clcer3's review.

It was cursorily reviewed at some revision prior to the last change by Clcer who passed it at that point - this review has been correctly commented out as it doesn't apply to the current revision of the code, but the reviewer's name has been correctly added to the list of past reviewers. If Clcer2 or Clcer3 had also reviewed the code prior to its last change, there would be no need to list their names in the past reviewer list - since they're already listed as current reviewers - nor to maintain a commented copy of their past review - since those reviews are superceded by their current reviews and are best accessible through the page's history.

The templates for review summary lines have been correctly maintained as the final comment block.

Full program, strictly conforming C90; BSDL; past reviewers: Clcer; current reviews: Clcer2 (cursory); Clcer3 (failed behaviour inspection);

as produced by the following wikitext:

{{codesummary                            |
type=            Full program            |
conformance=     strictly conforming C90 |
licence=         BSDL                    |
past-reviewers--no-line-breaks= [[User:Clcer|Clcer]] |
later-reviews--"none"-or-empty=       }}
{{passingreview|[[User:Clcer2|Clcer2]]|cursory}}
{{failingreview|[[User:Clcer3|Clcer3]]|behaviour inspection}}
<!--
{{passingreview|[[User:Clcer|Clcer]]|cursory}}
-->
<!--
{{passingreview|[[User:UserOnThisWiki|UserOnThisWiki]]|cursory or partial or complete}}
{{failingreview|[[User:UserOnThisWiki|UserOnThisWiki]]|(one or more of) syntax inspection, style inspection, portability inspection, behaviour inspection, compilation, desk-check, algorithm validation, casual/structured testing}}
-->

Example 2

The following summary line describes an incomplete snippet in the public domain written to demonstrate how part of the standard library could be implemented using C99-specific features. It has not been reviewed at any time. The templates for review summary lines have been correctly maintained as the final comment block.

Incomplete snippet, portable C99 in implementation namespace; public domain; past reviewers: none; current reviews: none

as produced by the following wikitext:

{{codesummary                         |
type=            Incomplete snippet   |
conformance=     portable C99 in implementation namespace |
licence=         public domain        |
past-reviewers--no-line-breaks= none  |
later-reviews--"none"-or-empty= none  }}
<!--
{{passingreview|[[User:UserOnThisWiki|UserOnThisWiki]]|cursory or partial or complete}}
{{failingreview|[[User:UserOnThisWiki|UserOnThisWiki]]|(one or more of) syntax inspection, style inspection, portability inspection, behaviour inspection, compilation, desk-check, algorithm validation, casual/structured testing}}
-->

Editing behaviour

Policy: Don't introduce technical errors into pages, particularly whilst making changes to grammar, spelling or style

Per heading.

Convention: Use talk pages for meta-discussion

Use the talk page associated with each article to discuss changes, such as explaining why a change to code was made, requesting clarification of a change or suggesting a change prior to making it.

Policy: Never use article pages for discussion that could occur on the talk page

Never use an article page for meta-discussion; articles should at all times contain reference material only.

Convention: Always leave a useful comment in the edit summary

Always use the edit summary box to describe the changes that you make when editing an article. It's very helpful for others to be able to see a brief summary without having to analyse a diff; this summary also occurs in places like the page's history listing where a diff is not immediately available. Don't mention some changes and fail to mention other changes - even if a change seems insignificant to you, it might be relevant to other people. A brief comment like 'fixed a typo' or 'many changes - see talk page' or 'miscellaneous rewordings for clarity' is fine for generic changes but for specific changes write something like 'fixed bug - foo was not defined and should have been bar'.

Leave the /* section identifier */ intact for section edits but also include a following comment (it's acceptable to trim long or messy section identifiers).

It isn't necessary to always include a summary for edits to talk pages, especially user talk pages, but it can be helpful for longer or significant edits.

Content and structural conventions

Namespaces

The main namespace contains all directly topical content. The 'clc-wiki' namespace (equivalent to the 'Project' namespace and previously identified as 'Clc') contains meta-topical articles describing this wiki: policies, procedures, conventions and configuration. The 'Planning' namespace is mostly historical and contains meta-topical pages used in the early planning stage of this wiki, as well as pages that properly belong in the 'clc-wiki' namespace. Links to pages in the 'clc-wiki' namespace are better written as the more generic 'Project', to ease any future renaming of this namespace.

Article and section titles

[this section is out-of-date and needs rewording - see the talk page]

Article titles and section headings should be as brief as possible without loss of meaning; a concisely-titled redirect page may be provided for articles with long titles when there's need for linkage from a Usenet post.

All characters in titles and section headings should be lowercase except for the first letter (which for article titles MediaWiki unavoidably capitalises) and any words that require it, such as the "C" and "S" in "the C Standard", acronyms such as "ISO" and standard identifiers that require it such as "FILE" or "INT_MAX".

When the initial letter of an article title should be lowercase, such as for a standard keyword, include Template:Firstlowercase as a template at the top of the article's content. When underscores are part of the title, include Template:Underscoredtitle. When both the initial letter should be lowercase and underscores are part of the title, include Template:Firstlowercaseunderscoredtitle.

(Pages in the K&R2 solutions section don't conform to this capitalisation convention - follow the existing conventions there)

Referencing the FAQ

The (comp.lang.c) C FAQ should be referenced through its home url, c-faq.com. One of the following forms should be used:

FAQ 17.12
FAQ 17.12 Which is correct, char *p or char* p?
FAQs 7.11, 6.14 and 6.16.
FAQ section 6. Arrays and Pointers

Reword long questions to fit on a single line and append [paraphrased] to the wording. Consistent paraphrasings are listed on Project:Policies:Short titles for FAQs.

K&R2 solutions

K&R2 solutions use index pages rather than categories for grouping and indexing solutions for chapters. In addition to the Category:KR2 Solutions category, there are index pages for each chapter - be sure to add new solutions to the index page.

From clc-wiki