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.
@worldsendless Agreed, code should be readable even with comments. Comments generally shouldnt be used to explain the code line by line unless your doing something counter interpretive that needs pointing out (which hopefully is rare). Comments should be focused and the method and class level describing what a method does, the valid inputs it accepts, what errors it will throw and why, and what return values it will provide as well as their type.
Comments shouldnt describe algorithms so much as interface bounaries (public methods and classes)
@freemo I agree. But related, comments shouldn't excuse coders from using code practices that maximize their code's comprehensibility (which, as you pointed out, may have a close limit if it's code for interfacing with external dependencies)