← Back to team overview

ooc-dev team mailing list archive

OOC best practices

 

OOC API isn't already consolidated but, with rock, I think we can say that pretty few things will change around current syntax and grammar.

So, can it be interesting to begin to set a *best practices guide* ?
The goal isn't to constrain anybody but I think some little rules can help about readability and code reuse.

Can we start to talk about it ? An example can be the Python style guide : [http://www.python.org/dev/peps/pep-0008/]. Points that should be discussed :

* Indentations
* Line length
* Encodings
* Whitespaces
* Naming conventions
* Comments
* ....

Apart from style guide, I d'like to talk about documentation. Python (it's my world, sorry) uses docstring [http://www.python.org/dev/peps/pep-0257/]. What's your point of view about standardizing how we should document our ooc projects ?

What do you think about using a *markup language* within it and to have an 'official' one; as it can automate documentation extraction, as with Sphinx for Docs-OOC.

In my mind, if you're allright about using a lightweight markup language, there are two good candidates :

- *Markdown*, and eventually Markdown Extra / extensions [http://daringfireball.net/projects/markdown/] - RestructuredText [http://docutils.sourceforge.net/docs/user/rst/quickref.html]

Although RST and MD have closer syntax, I can say that :

- *RST* is by default more powerfull than MD : tables, ids, classes... It have good Python tools to translate into many formats (ODT, PDF, XHTML, LaTex, S5, Manpage...); it's extensible and there is Sphinx. Furthermore, RST is already used by OOC with the official docs.

- On the other side, MD have many interpreters, and some are written in C. It's most widely used and known, and we can easily integrate it with the current official website (Dokuwiki and Wordpress plugins are available).

Personally, I incline to RST, maybe from habit, but I also think RST is more powerful, more structured than MD. It also have more output formats available. Writing an OOC Rst2Xhtml program should be a nice project, as it can be largely faster than the official package. As I know it's not a priority at all, note that it could be one thing I have to write at work in a couple of months from now.



Follow ups