Update contribution guidelines - code style, actor's description

[oamg]

Update contribution guidelines - code style, actor's description

[bocekm]

class MyActor(Actor):
    """
    This is a lengthy
    multiline docstring.
    """
    name = 'my_actor'

    def process(self):
       """Short one-line docstring."""
       mutliline_string_variable = (
           'I am a multiline string.\n'
           'This is my second line.'
       )

[bocekm]

@vinzenz, @shaded-enmity, on Cabal we have agreed on the following multiline string formatting, which is actually incorrect as it includes whitespaces you most of the times don't want:

class MyClass():
    multiline_attribute = '''
        I hold some lengthy
        multiline string.
    '''

Take a look if you fancy the alternative formatting I used in the previous comment. I think it's better than:

mutliline_string_variable = 'I am a multiline string.\n' \
                            'This is my second line.'

I fear neither look pythonic enough for you. If so, propose another.

[vojtechsokol]

What about this for multiline strings?

multiline_string = ('first line',
                    'second line')

And regarding multiline docstring, why not use PEP257? I.e. for one liner a phrase (ending in a period) with opening and closing quotes on the same line and for multi-line docstring the first line would be the same phrase, followed by a blank line, followed by a more elaborate description:

class SimpleClass(Object):
    """This is a simple class."""

class ComplicatedClass(Object):
    """
    This is a more complicated class.

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc porta sed
    urna venenatis faucibus. Phasellus at bibendum ligula, a posuere metus.
    """

[bocekm]

The multiline_string you propose is actually a tuple. So, yeah, in general I'm for the parenthesis version as I mentioned two comments above.

As to the use of PEP257, the thing is that it allows a bit of variations: "The summary line may be on the same line as the opening quotes or on the next line."
We'll allow just "on the next line". I guess that's the only difference. So I'll leave the PEP257 in the contribution guidelines, and just mention this one difference.

So, to wrap it up, here's the string & docstring formatting:

class MyActor(Actor):
    """
    Start with a single-line brief summary of the actor (under the triple quotes).

    Leave a blank line below the summary and then describe the actor's behaviour
    here in detail.
    """
    name = 'my_actor'

    def process(self):
        """This is a simple method."""
        complicated_method()

    def complicated_method():
        """
        This is a more complicated method.

        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc porta sed
        urna venenatis faucibus. Phasellus at bibendum ligula, a posuere metus.
        """
        mutliline_string = (
            'I am a multiline string.\n'
            'This is my second line.'
        )