alexeyinkin commented on PR #24338: URL: https://github.com/apache/beam/pull/24338#issuecomment-1346838678
@damondouglas I normally comment pieces that I am satisfied with and perceive as non-self-documenting. Some examples of that are `PagePath` classes, posting messages with JavaScript, etc. I normally do not document code that: 1. **Looks self-documenting** to me. 2. **Is up for refactoring**. Examples are current widgets for code sharing. We do have 5 widgets with `*ShareTab*` in their names, and their nesting is complex. Still I think it makes little point to document them because they do not have sound reasons to be separate, and I plan to simplify this in a few months. 3. **Is self-documented once a specific API is understood**. For example, most of Flutter developers are not familiar with Navigator 2.0 API and its `Page` classes, yet I think that a project's source is not the right place to educate on that. This is my habit for consistency when commenting. Please help me adjust to yours if you think that any of the above categories deserve more comments. Also I have just added comments to 45+ files. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
