kirkshoop
Commenting the code in tutorial style
Hi,
This little project along with the blog posts is a perfect introduction to Rx/RxCpp. However, if it is taken as a tutorial, the blog posts are too high-level and omit some details a newbie would definitely have. It would be great to add more detailed comments to the source itself, as it is written in a top-down sequential manner which is ideal for a right-in-the-source tutorial. I started commenting the code myself ("commenting" branch on my fork of twitter app: https://github.com/kirkshoop/twitter/compare/master...elelel:commenting ), but since I myself am using it to familiarize with RxCpp library, I have doubts about their quality.
The approach I've taken is more or less like this:
- Comments should address three areas: the twitter app logic itself, the Rx aspects (shared among other language implementation), the RxCpp aspects
- They should be written to be read top-down, e.g. omitting concepts already explained before
- Any detailed explanation should be an external WWW link to make sure we are not overloading the code
- Anything I'm not sure about is marked with "TODO"
The problematic part for me are those TODOs, since most of them I'm unable to resolve on my own. Please let me know if converting the source in a tutorial in such way is of interest to you. In this case I'll continue commenting the source assuming we'll somehow resolve this part. Otherwise there'll be little point in continuing for me because it looks like I won't be able to cover too many important details.
Thanks
👍 I love this idea and approach. I will be happy to help with the todos.
I would like to make this incremental to minimize merge issues as the code continues to change.
So please make PR's even if they have TODOs in them still, each comment makes the code better.
How would you like to manage the todo list? I could just comment on them in a PR, or use issues - what is your preference?
Frankly, I don't know how it's better to deal with TODOs, because of that I opened this issue. There're just too many of them and it's an overkill to open separate issues for them. I think it's easier just to look them over in the source and edit, e.g. with a single correction commit right after the merger. I marked them as "TODO" with that in mind, most of IDEs I know by default make a separate list for such comments. I think GitHub doesn't have this functionality when commenting PRs, though. In any case, for me any variant is ok.