# Poor man's inline comments: Should we suggest using these?

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()


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()


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?