I agree for inline code comments, like, “# Save the sprocket”, right above the line that saves the sprocket. Does this include documentation? Because when I see a prepareForSave function that references 10 other functions and I just want to know, “Is this mutating and how is it preparing for save and when should I call it?”, having the author spend 15 seconds telling me is less time consuming than me spending 5 minutes reading code to find out. Anyone who has read API docs has benefited from documentation.
No, commenting a function should be commonplace, if not only so that your IDE/editor can use the documentation when the signature is found elsewhere in your code.
Within a function, though, basically means that something gnarly is happening that wouldn’t be obvious, or that the function is doing more than it (probably) should.
I agree for inline code comments, like, “# Save the sprocket”, right above the line that saves the sprocket. Does this include documentation? Because when I see a
prepareForSavefunction that references 10 other functions and I just want to know, “Is this mutating and how is it preparing for save and when should I call it?”, having the author spend 15 seconds telling me is less time consuming than me spending 5 minutes reading code to find out. Anyone who has read API docs has benefited from documentation.No, commenting a function should be commonplace, if not only so that your IDE/editor can use the documentation when the signature is found elsewhere in your code.
Within a function, though, basically means that something gnarly is happening that wouldn’t be obvious, or that the function is doing more than it (probably) should.