"sub-comments" inside of "main-comments"

[Rudi Hammad]

Hi,
this is just a weird style question. I often find the need to comment something specific inside of a more generic coment. This is what I mean:

# Main comment A
some code...
# Sub comment A1
some code...
# Sub comment A2
some code...

# Main comment B
some code...
# Sub comment B1
some code...
# Sub comment B2
some code...


This way all the comments, make seem like the code is at the same level. what I really want is to show that the code in the organized in different levels or steps.
So what I do is something like

# --[ Main comment A ]-- #
some code...
# Sub comment A1
some code...
# Sub comment A2
some code...

# --[ Main comment B ]-- #
some code...
# Sub comment B1
some code...
# Sub comment B2
some code...

Do you see what I mean?
But I am not very happy with it. I know this is not relevant at all, but I wonder if there is a convention for this. PEP doesn´t go into something that specific I think
I also tried

# -------------------------- #
#  Main comment A #
# -------------------------- #
some code...
# Sub comment A1
some code...
# Sub comment A2
some code...

# -------------------------- #
#  Main comment B #
# ------------------------- #
some code...
# Sub comment B1
some code...
# Sub comment B2
some code...

but now I am consuming 4 extra lines for nothing with  # -------------------------- #

cheers

[Justin Israel]

Can you give a concrete example instead of an abstract one? It would be good to see how you are trying to comment your code and why this concept of "sub comments" is necessary.

Also, I am not sure if it's a PEP thing or not, but it's at least my opinion that you should avoid arbitrary comment "styling", like doing #####---- and what not. Especially in the middle of function bodies. There was a point in my earlier python career when I followed others examples of doing it to separate classes and free functions within the module, but now I find it annoying. It's quite noisy, and would be even noisier to find within a function body. And to me it would seem like if you need that kind of separation between so many blocks, that maybe the function is too big and should be refactored? Is the function possibly doing too much work, which requires you to visually break them down in comments?

Justin

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/8d11364b-74aa-4e17-ace4-aeeb5cc26989%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Marcus Ottosson]

Sounds like a typical usecase for docstring along with line comment.

def my_function():
  """Short description of function

  Longer description, with argument signature and return type etc
  related to the function overall.

  """

  # Line comment, related to upcoming line or series of lines.
  code here

This, along with “cyclomatic complexity“, in particular about keeping functions small, should encourage short and concise code.
​
Was this what you meant?

​

[Rudi Hammad]

yes, this is a specific example extracted from my last post

https://pastebin.com/te0EEAeC

So in the example, the main comments are the ones beginning with # // The main comment
I feel that I can visualize better the body of the code with # // The main comment
And then the sub comments would be the ones just like # The subcomment

For me, it helps reading the code, but I guessI should not create my own comment symbol..

Marcus, usually I do the doc string comment after the methods. But again, it might be completely irrelevant but instead of using """ """ I use ''' ''' and I don´t jump a line.
It looks more compact. But I guess I should follow PEP event if I have other point of view.


Justin, I read once that if you need to do the kind of comments that I do, or put inside the code a divider like # -------------------------------------------# it is because you should be using
more functions, and not putting everything inside of the same function.
I have seen codes like that, with 25 functions or more. But many of those functions had inside 10 or less lines of code. Doesn´t it make it more confusing with so many functions?


Also, I recently started studying c++, and it seems that they don´t care as much about all this kind of things.

[Justin Israel]

On Thu, Apr 13, 2017 at 8:48 AM Rudi Hammad <rudih...@gmail.com> wrote:

yes, this is a specific example extracted from my last post

https://pastebin.com/te0EEAeC

So in the example, the main comments are the ones beginning with # // The main comment
I feel that I can visualize better the body of the code with # // The main comment
And then the sub comments would be the ones just like # The subcomment

For me, it helps reading the code, but I guessI should not create my own comment symbol..

Yes. So like you said, it is just your own convention that helps you to read it. But anyone else reading your code isn't going to understand your documentation conventions unless they have had experience reading your code. Honestly, comments should just be comments and I don't think they should need specialized formatting unless they are being picked up by a documentation generator (i.e. Napoleon or RST style). If I were to read your code, I would just see extra symbols surrounding the comments I need to read.

 

Marcus, usually I do the doc string comment after the methods. But again, it might be completely irrelevant but instead of using """ """ I use ''' ''' and I don´t jump a line.
It looks more compact. But I guess I should follow PEP event if I have other point of view.


Justin, I read once that if you need to do the kind of comments that I do, or put inside the code a divider like # -------------------------------------------# it is because you should be using
more functions, and not putting everything inside of the same function.
I have seen codes like that, with 25 functions or more. But many of those functions had inside 10 or less lines of code. Doesn´t it make it more confusing with so many functions?

No, it can make your code more composable and reusable. It helps to break apart your logic into specific concerns. It also helps with mocking in tests, and for changing functionality later. Sure there are ways to get it wrong and make something a function that doesn't need to be. Its a case-by-case decision.

 

Also, I recently started studying c++, and it seems that they don´t care as much about all this kind of things.

I don't see examples in the Google C++ style guide, showing that one should use //-------- divider lines between blocks of code. All of the comment sections show using the standard // and /* formats for adding text. But they don't recommend decorating your file for visual separation. It can become annoying when you create a new function in someone elses existing code, and you have to follow what they have been doing with some divider line of a specific length, and they may have done something like this:

// -------- Utility Functions ------------------

And then you have to try and match the right length based on the new words that fall within that divider. Its all kinda unnecessary given a file is supposed to follow the "single responsibility principle" and have logic that is all related to the same goal anyways. Comments should be enough. And it is the comments anyways that contribute to the documentation. Syntax highlighting should also help to visually separated code.

 

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/39a72965-9d40-45d9-a66c-5eb5b049253c%40googlegroups.com.

[Rudi Hammad]

Understood.
I´ll follow your advices. Thank you both

[Rudi Hammad]

Hello again I have been reading a bit more about doc strings. And as marcus said, PEP 257 says that docstrings should be like

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero

I am trying to convince my self to use this, but it I dont like it.

Why not 
def complex(real=0.0, imag=0.0):
    """
    Form a complex number.
    Description: This script does this and that
                 and other stuff
    Status: work in progress
    Extra notes: need to implement something somewhere
    Author: some guy
    """

    if imag == 0.0 and real == 0.0:
        return complex_zero

I don´t want to bore you again with the same questions. I try to follow every universal convention, I just
don´t understand why in the first line I should begin intermediately after """ and then jump a line, and then the last line alone """
For instance, I do understand how 80 char per lines reads better, and that I should not create my own style, but this docstring style. I don´t know

R

[Marcus Ottosson]

I just don´t understand why in the first line I should begin intermediately after “””

Conventions such as these enable external tools to operate on your docstring and make certain assumptions, such as what types arguments expect and their description. The first line is typically reserved for a summary of the docstring, and having it on the first line provides two advantages that, aside from tools, I sometimes benefit from myself.

1. Easy access, always the first line. (See example below)
2. Perhaps more importantly, it visually prohibits the summary from taking up multiple lines, as the next line would have a different indentation due to the “””

def my_function():
  """First line

  Subsequent lines
  are here.

  """

summary = my_function.__doc__.split("\n")[0]
print(summary)

# Try putting the summary on the next line

Some tools assume the first line is your summary (such as Sphinx), but if you aren’t using those tools or making tools yourself that depend on this convention, it probably isn’t the end of the world if you go with what you prefer.

Speaking of preference, tools such as Sphinx and docstring conventions, there is another player on the block that I personally prefer.

• Napoleon

​The important bit I think is that you find something you like that (1) remains consistent, (2) isn’t entirely alien to others (like us) if you want others to read it and (3) works with the tools you would like to use, such as Sphinx.

​

[Rudi Hammad]

That make more sense now. I´ll do it like that.
I am not sure about leaving a blank line between in the end of the doc string . According to PEP 8 it should be like this right?

def my_function():
  """First line

  Subsequent lines
  are here.
  """
summary = my_function.__doc__.split("\n")[0]
print(summary)

Anyway, I am becoming a style freak when there are so many thing I need to learn yet.
So yes, I´ll stick with those conventions. Thx Marcus

[Justin Israel]

On Wed, Apr 26, 2017, 6:25 AM Rudi Hammad <rudih...@gmail.com> wrote:

That make more sense now. I´ll do it like that.
I am not sure about leaving a blank line between in the end of the doc string . According to PEP 8 it should be like this right?

I don't usually preserve that first line when doing multi line docstrings. But I have always been using Sphinx RST and more recently Sphinx Napoleon, and haven't noticed an issue. 

def my_function():
  """First line

  Subsequent lines
  are here.
  """
summary = my_function.__doc__.split("\n")[0]
print(summary)

Anyway, I am becoming a style freak when there are so many thing I need to learn yet.
So yes, I´ll stick with those conventions. Thx Marcus

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/bf4a6d7b-657a-4a64-a7de-4aab703d2b16%40googlegroups.com.

[Marcus Ottosson]

No problem, happy to help.