5
\$\begingroup\$

It just occurred to me that the markup test I had done could look better:

Original

# Finds sum of all multiples of 3 and 5 from 0 to 999 

def find_multiples():
    global numbers

    for i in range(0,1000):
       if i%3==0 or i%5==0:
           numbers.append(i);

numbers = []

if __name__ == '__main__':
    find_multiples()
    print sum(numbers)

Inline review

No-nonsense pure text comments, could use /// as line starter for many languages.

# Finds...
###-^ Put this in a docstring

def find_multiples():
    """Finds sum of all multiples of 3 and 5 from 0 to 999 """
###-^ This allows you to "from x import find_multiples,  help(find_multiples)"
    numbers = []
###-^ Avoid globals
    for i in xrange(0,1000):
###-^ Use xrange if Python 2.x
       if not (i % 3) or not (i % 5):
###-^ Add spaces around operators, simplify
###-^ the boolean/numeric checks
           numbers.append(i);  


###-^ Removed

def main():
###-^ Allows calling main many times, e.g. for benchmarking
    numbers = find_multiples()
    print sum(numbers)

if __name__ == '__main__':
    main()

Poor man's inline comments

Now with muted or louder comments!

# Finds...
-^ Put this in a docstring
def find_multiples():
    """Finds sum of all multiples of 3 and 5 from 0 to 999 """

-^ This allows you to "from x import find_multiples, help(find_multiples)"

    numbers = []
-^ Avoid globals
    for i in xrange(0,1000):
-^ Use xrange if Python 2.x
       if not (i % 3) or not (i % 5):
-^ Add spaces around operators, simplify -^ the boolean/numeric checks
           numbers.append(i);
-^ Removed
def main():
-^ Allows calling main many times, e.g. for benchmarking
    numbers = find_multiples()
    print sum(numbers)

if __name__ == '__main__':
    main()

Blockquoted inline comments

Looks OK, but is very fragile and hates long lines:

# Finds...

-^ Put this in a docstring

def find_multiples():
    """Finds sum of all multiples of 3 and 5 from 0 to 999 """

-^ This allows you to "from x import find_multiples, help(find_multiples)"

    numbers = []

-^ Avoid globals

    for i in xrange(0,1000):

-^ Use xrange if Python 2.x

       if not (i % 3) or not (i % 5):

-^ Add spaces around operators, simplify -^ the boolean/numeric checks

           numbers.append(i);

-^ Removed

def main():

-^ Allows calling main many times, e.g. for benchmarking

    numbers = find_multiples()
    print sum(numbers)

if __name__ == '__main__':
    main()

Is the poor man's style an improvement for inline comments? Should we cite it as an option in the FAQ?

\$\endgroup\$
5
\$\begingroup\$

Just from my point of view i like the Inline review better as it doesn't hurt the syntax highlighting that much and especially It's easier copy/pasteable.

When improving on some small pieces of code i'd like to be able to cp for a syntax for functionality check, edit, and put it back. So i really like the idea of using language dependend comments. (even so ### should work great for many languages and sets a good standard)

\$\endgroup\$
  • \$\begingroup\$ +1 I prefer the inline as well \$\endgroup\$ – Mark Loeser Jan 20 '11 at 13:38

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .