frc-docs icon indicating copy to clipboard operation
frc-docs copied to clipboard

Add discussion of command organization

Open RobinsonZ opened this issue 2 years ago • 7 comments

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.

RobinsonZ avatar May 15 '22 23:05 RobinsonZ

~~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.

RobinsonZ avatar May 16 '22 20:05 RobinsonZ

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)

Starlight220 avatar May 16 '22 22:05 Starlight220

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 avatar Jul 07 '22 10:07 Starlight220

@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 avatar Jul 10 '22 03:07 RobinsonZ

@RobinsonZ what do you think? since this is originally your PR, I'd be happy for your review as well.

Starlight220 avatar Oct 08 '22 19:10 Starlight220

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.

Daltz333 avatar Oct 09 '22 16:10 Daltz333

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?

Starlight220 avatar Oct 10 '22 16:10 Starlight220