Actually sidestepping the "comments bad" debate, if you can't read your code two weeks later, you have bigger problems. #readablecode

@worldsendless Depends on if its an issue with local code reasability, or overall complexity. Code can be written well enough you understand what each line on its own does but not why it is doing what it is overall regarding its interaction with other modules.

For example a lot of times the type a method returns may be many different things and those things ultimately are defined by the underlying APIs. If a method is passing along the return value from one of a dozen different methods depending on some condition then you'd have to read the documentation on 12 different methods just to understand what your method is expected to return. If its documents then you need to read just the documentation of your one method.

@freemo Excellent point! Interfacing with external services is a comman use-case that should be remembered; negotiations with programs that are not your own are indeed a case where some explanation may me welcome

@worldsendless Its equally true if those 12 methods arent external, as then you need to go look at the code for all 12 methods.

Honestly IMO there is **never** an excuse not to document methods unless the program you are writing is very small to the point of being a simple script. Even then its still probably a good idea.