ooc-dev team mailing list archive

[Friedrich Weber <fred.reichbier@xxxxxxxxxxxxxx>]

Huhu!

On 02.05.2010 13:43, Fabien Bourgeois wrote:
> 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.

Yeah, we certainly need this! I'll just throw in my opinion here. :-)

> 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

I like Python, I like 4 spaces.

> * Line length

Hm. 79 characters as a guideline?

> * Encodings

UTF-8?

> * Whitespaces

I also like Python's style here, with one exception: Function
definitions should have a space between the `func` keyword and the
arguments::

	doSomething: func (...) {
		/* ... */
	}

> * Naming conventions

We should use thisStyle for functions and variables, UppercasedCamelCase
for classes, covers etc. and UPPERCASED for constants (huh, looks so
aggressive)
Package names should be lowercased (net/, io/, lang/). I'm not sure
about modules. What about this: Capitalized if mainly containing a class
of this name (structs/HashMap), lowercased if the module name is more of
a description of its contents? (lang/types, ...).

> * Comments

Hm. // for one-line comments, /** */ (oocdoc) for documentation, /* */
for everything else?

> 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 ?

Well, we theoretically support everything that sphinx supports, with
some extensions. ooc-docs uses a sphinx extension that adds some
ooc-specific roles and refs (so you can do :cover:`String` to reference
String, for example)

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

Hm, I smell problems since we're using MD for ORCs and RST for docs. If
we need a universal choice, I'd also tend to use reStructuredText.

Cheers,

Friedrich