Cobra Style Guide

[travisby]

Hello,

Is there an equivalent to Python's PEP8 for Cobra? I want to start writing a few play projects, and would like to follow a nice style guide - if one exists. If not, I'll just refer to the Cobra source for most of my questions.

In addition, is there any programming conventions/styles prevalent in Cobra? As an example, it's more popular to wrap - rather than extend - a class in Python.

[Charles]

I imagine we'll have one eventually, but the motivation has been fairly low because many of these things are actually enforced by the compiler:

-- Classes, interfaces, etc. must be capitalized.

-- The names of members such as methods and properties must start lower case (or underscore and then lowercase).

-- Parameters and local vars cannot start with underscore or upper case.

-- Members must be accessed through a dot (.) or if they start with an underscore, they can be access directly.

-- Indentation must be done with tabs or 4 spaces per level.

-- Per line, indentation cannot be a mix of tabs and spaces. Use one or the other.

-- The above two rules have limited exceptions when doing "continuing line" indentation where you may append 1 - 3 spaces on the indentation for the purpose of making the continuation line match up with the original line.

Note that these rules combine to give a fairly uniform look to code between programmers and projects.

Also if you dive into a bit of Cobra code like this:

color = _backgroundColor

... you automatically know that "color" is a local var (or parameter) and that _backgroundColor is class member. This is very different than Java and C# where locals and members can look syntactically the same. Good style can make Java and C# more readable, but I've seen so much "bad style" code in those languages that I decided to enforce some rules in Cobra.

-- Another difference with Python is that when you write in Python:

Code: Select all

foo = self.bar


You could be getting a reference to a method. Or if "bar" is data, you are getting a value, instead of a reference. Or if "bar" is a method with a @property decorator, you are not getting a reference to the method, but the value from executing it. Bleck. In Cobra, there is one way to get a reference and that's using the "ref" keyword in front of the expression:

foo = ref .bar
foo = ref x.y.z

If you don't see "ref", you are invoking a method, property or getting the value of a variable.

Okay, I lied. "foo = Bar" gets you a reference to a class. But since classes are capped, you still know what's going on at a basic level when you read someone else's Cobra code.

-- Our community member "Hops" added default parameter values like you see above for Exception.description, as well as keyword arguments. I use these quite a bit, but you won't see them much in existing examples or the Cobra compiler because they are relatively new. They work just fine though.

-- You were asking about other prevalent conventions beyond syntax. One that I use often enough is extending existing types. In an application I recently wrote, I needed a particular kind of description for an Exception. In Python, you would probably make a function for this:

Code: Select all

# python
def description(exc):
    ...
    return s
# and use it like:
    file.write(description(someException))


If you had more than one "description", you'd have to make the names unique, or use the same func and have it branch on type, or put the funcs in separate modules (and then access them with dotted notation, or use import...as). In Cobra, I just extend the type:

extend Exception

    def description(separator as String = '; from ') as String  # is this the right separator?
        sb = StringBuilder('')
        e, sep = this to ?, ''
        post while e
            sb.append(sep)
            sb.append('[e.typeOf.name]: [e.message]')
            e, sep = e.innerException, separator
        return sb.toString
# and use it like a normal method:
    file.write(someException.description)

In fact, Cobra comes with several extension methods to add more convenience to the .NET standard library. Here they are with signatures, docs, contracts and tests:
http://cobra-language.com/trac/cobra/wi ... ionMethods
http://cobra-language.com/trac/cobra/wi ... ypeMembers

Here are brief docs on using "extend":
http://cobra-language.com/trac/cobra/wi ... Extensions


Is that helpful?


There are probably other syntactic rules and conventions, as well as "code structure" conventions, that I have failed to mention simply because I have "internalized" them. It would be interesting for someone new to Cobra to post observations and questions to this thread as you learn the language.

[travisby]

Is that helpful?

Very!

That was an excellent writeup. Thank you.

I have to admit, a lot of those enforced conventions were a reason I was looking at Cobra (I'm sure you're aware of how painful it is to work with someone who doesn't understand the difference between 4 spaces and 1 tab in python...)

Any further observations or questions I have, I will keep posting in this topic. Hopefully this can become a nice resource for incoming Cobra users.

Thanks again!