frc-docs
frc-docs copied to clipboard
Add discussion of command organization
Definitely WIP, but throwing this up so people can take a look at it because I might be entirely off base with the general vibe of the article.
I plan to write a more prescriptive tutorial that can replace "Structuring A Command-Based Robot Project" to go with this more in-depth discussion.
Also, this needs C++ examples throughout, I can probably take a crack at it but I don't have any experience with WPILibC so I'm leaving them as TODOs for now.
This also intersects with #1808, but I'm doing it as a separate PR for now in order to not cause conflicts. Happy to move things around if that's desired.
~~It seems like there's an unrelated failure in the link checking task because https://www.analog.com/en/landing-pages/001/first.html has some sort of blocking going on (at least, I can access it from my machine, but the link checker isn't happy about it). Not sure what to do about that.~~ Seems to have fixed itself, maybe the website just happened to be down last night.
What do you think about this sort of structure for the article?:
- introduction
- (what you have now is mostly good)
- inline commands
- problem (=lack of reusability)
- method factories
- explanation
- example code
- (dis)advantages
- subclassing
CommandBase
- (same 3 subitems as method factories)
- static factories
- (same 3 subitems as method factories)
- subclassing
CommandGroupBase
- (same 3 subitems as method factories)
- (maybe somewhat of a summary here? like a table comparing pros and cons or something)
(maybe flip the order between static factories and extending CommandGroupBase
)
(side note: the lack of linearity in the discussion here is really confusing)
seeing as this hasn't been touched in a few months, I want to ask: @RobinsonZ do you intend to continue working on this? if not, do you mind if I take over?
@Starlight220 Yeah, unfortunately I've had considerably less free time than expected this summer with internships and all. Feel free to take over, hopefully you find some of this existing copy useful.
@RobinsonZ what do you think? since this is originally your PR, I'd be happy for your review as well.
I think it would be a good idea to have a visual representation (graph/tree) of project structure. There's a lot of valuable text here, but images speak a thousand words.
Thing is, this article is less about project structure and more about structuring/writing the command in a certain way. I can't think of a diagram that would be relevant/helpful; if anyone else has an idea I'm all ears. Maybe there's a more relevant name for this article?