Skip to main content
added syntax-highlighting
Source Link
Deduplicator
  • 9.3k
  • 5
  • 34
  • 53

There are already a lot of good answers, but there is a special case worth mentioning.

If your one-line statement needs a comment, and you are able to clearly identify (which means: name) its purpose, consider extracting a function while enhancing the comment into API doc. This way you make the function call easier faster and to understand.

Interestingly, the same can be done if there is currently nothing to do, but a comment reminding of expansions needed (in the very near future1)), so this,

def sophisticatedHello(): # todo set up say("hello") # todo tear down 
def sophisticatedHello(): # todo set up say("hello") # todo tear down 

could as well changed into this

def sophisticatedHello(): setUp() say("hello") tearDown() 
def sophisticatedHello(): setUp() say("hello") tearDown() 

1) you should be really sure about this (see YAGNI principle)

There are already a lot of good answers, but there is a special case worth mentioning.

If your one-line statement needs a comment, and you are able to clearly identify (which means: name) its purpose, consider extracting a function while enhancing the comment into API doc. This way you make the function call easier faster and to understand.

Interestingly, the same can be done if there is currently nothing to do, but a comment reminding of expansions needed (in the very near future1)), so this,

def sophisticatedHello(): # todo set up say("hello") # todo tear down 

could as well changed into this

def sophisticatedHello(): setUp() say("hello") tearDown() 

1) you should be really sure about this (see YAGNI principle)

There are already a lot of good answers, but there is a special case worth mentioning.

If your one-line statement needs a comment, and you are able to clearly identify (which means: name) its purpose, consider extracting a function while enhancing the comment into API doc. This way you make the function call easier faster and to understand.

Interestingly, the same can be done if there is currently nothing to do, but a comment reminding of expansions needed (in the very near future1)), so this,

def sophisticatedHello(): # todo set up say("hello") # todo tear down 

could as well changed into this

def sophisticatedHello(): setUp() say("hello") tearDown() 

1) you should be really sure about this (see YAGNI principle)

Source Link
Wolf
  • 640
  • 2
  • 6
  • 26

There are already a lot of good answers, but there is a special case worth mentioning.

If your one-line statement needs a comment, and you are able to clearly identify (which means: name) its purpose, consider extracting a function while enhancing the comment into API doc. This way you make the function call easier faster and to understand.

Interestingly, the same can be done if there is currently nothing to do, but a comment reminding of expansions needed (in the very near future1)), so this,

def sophisticatedHello(): # todo set up say("hello") # todo tear down 

could as well changed into this

def sophisticatedHello(): setUp() say("hello") tearDown() 

1) you should be really sure about this (see YAGNI principle)