Re: documenting code, I've gotten a lot of conflicting advice over the years, with some people insisting code should be documenting, and others insisting on docstrings.
For loosely typed dynamic languages, docblocks on interfaces (function/method definitions, interfaces, etc) are a good idea.
For languages that require types in their interfaces, it is helpful for larger units(classes, functions, methods) to have a summary comment.
Inline comments are still very useful for explaining how and why of implementation details.
While I reject the stance that you should never have comments, I also see cases where better names and simpler logic can alleviate the need for more comments.
For loosely typed dynamic languages, docblocks on interfaces (function/method definitions, interfaces, etc) are a good idea.
For languages that require types in their interfaces, it is helpful for larger units(classes, functions, methods) to have a summary comment.
Inline comments are still very useful for explaining how and why of implementation details.
While I reject the stance that you should never have comments, I also see cases where better names and simpler logic can alleviate the need for more comments.