On Thu, Apr 13, 2017 at 8:48 AM Rudi Hammad <[email protected]> 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 [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/python_inside_maya/39a72965-9d40-45d9-a66c-5eb5b049253c%40googlegroups.com > <https://groups.google.com/d/msgid/python_inside_maya/39a72965-9d40-45d9-a66c-5eb5b049253c%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAPGFgA1Wy7Dw9oocAVZcqsdLXaB%3DY45paXjouAp9nOknV2ABFw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
