[Split Thread] Differences between PROS and VEXCode and Respective Documentation

[sazrocks]

@anon4126930

I’m going to be brutaly honest…

Connor, I’m getting vibes from the last time you went on a tirade against PROS here on the forum.

@sazrocks

@anon4126930

Honestly, this may sting a bit

@anon4126930

Allow me to explain

@anon4126930

Are you now going to tell me I’m going to need to pop open a dictionary or click on each and every link to understand what each and every search result means? Are you kidding?

@anon4126930

here you are, telling me that VEXcode is just as easy to learn as PROS? Absolute bogus of a statement, I tell you.

@anon4126930

What the hell is this?

@anon4126930

Jesus, we’re talking about the MAJORITY of the people in VEX. I swear to you that most people will not even remotely understand this structure nor wish to devote the time to understand it unless they have the motivation to do so.

@anon4126930

What the HELL does this stuff mean?

@anon4126930

Do I need to open up google now to try to understand each of these terms? It’s almost as if this is a forbidden English language.

@anon4126930

Like… Do you really think it is just as easy?

@anon4126930

Are you not understanding that the component of “easy” also includes the fact that VEX Robotics made both VEX V5 and VEXcode, and that VEX Robotics also includes a VEX Forum which has amazing people like @jpearman to help add convenience to those who are new to the VEXcode environment?

@anon4126930

Do you not understand that the individuals directly responsible for VEXcode are being paid to be accessible right at your fingertips?

@anon4126930

Please, @Unionjackjz get a load of yourself. It is obvious VEXcode is easier to learn than PROS.

@anon4126930

However, you will realize that even with LemLib, even odometry configuration seems confusing and the path planning seems un-necessarily complex and could have been simplified a lot better using a list of lists/vectors.

Potentially in the future, I am working on making a lib of my own, planned to be available for VEXCode and PROS upon release that pretty much fixes a lot of the issues of lackluster libraries:

So here’s the deal. I’m going to go point by point through your posts and point out numerous inaccuracies (as I have done several times in the past now). However, the ultimate problem with your posts here is your attitude. This is a collaborative environment where we can come together to learn new things and help inspire students to learn real-world STEM skills while competing in robotics. There is no need to demean the freely released work of others in the manner you are currently. If you want to help, contribute patches to the projects you are trashing (they are all open source for this exact purpose).

@anon4126930

The only reason why I used VEXCode primarily is because PROS documentation is unnecessarily complex, however VEXCode doesn’t really have documentation.

The irony of this statement is astounding. Are you seriously saying that having no documentation would be superior to PROS’s documentation? And how would having no documentation be superior for new students learning to program!?

Additionally, the assertion that VEXCode doesn’t have documentation is plain false. VEXCode has an online API reference, as well as documentation within vexcode and the VEX VSCode extension themselves.

@anon4126930

But one thing VEXCode has that made me choose it primarily was because VEXCode has @jpearman, a genuine godsend on this forum.

James is indeed an invaluable resource for students who use VEXCode on this forum. But, treating a person as a substitute for documentation as you propose is not ideal, and while I can’t speak for him I would imagine he would appreciate it if more people utilized the documentation that exists rather than going to him first.

@anon4126930

And honestly, I didn’t use PROS because any question on any server is just “RTM” to literally a very non-intuivive and unnecessarily complex documentation page.

This is plain false. There are countless examples of students having trouble with PROS (and VEXCode) being helped through back-and-forth troubleshooting over the course of hours and days in a number of servers. This is true even for high level and fairly complex problems, and can involve hundreds of messages back and forth. People will be directed to documentation first if their question can be answered directly by it, which reduces redundant information and saves the time of everyone involved. However, if they come back and still have questions that are not answered by the documentation (as has happened many times), there are dozens of users ready to help them through whatever challenge they are having.

@anon4126930

I also found that PROS documentation has zero visual differentiation between a header and code.

@anon4126930

some codes are examples and others are meant to inform. And PROS doesn’t even try to explain the difference and assumes that anyone reading the documentation knows the difference between the two.

Again, this is false. Here, let’s take a look at a page of the PROS 3 docs:

Here we can see that the function prototype and example code utilizing that function are clearly delineated, as they are throughout the documentation. Let’s take a look at the PROS 4 docs:

Please explain where this “zero visual differentiation between a header and code” is in this screenshot.

@anon4126930

PROS can be easy to understand but the documentation decides not to be.

This is the first of several times where you imply that the PROS team has deliberately made their solution hard to use for students. This is not only patently false, it is hurtful, offensive, and it wrongfully impugns the character of the students who donate their time to the PROS project.

@anon4126930

If you look at Okapilib, you will realize how dated its documentation is, alongside how un-intuitive it is for newcomers.

First, Okapilib is and was always a separate project from PROS, developed by a different group of people, so I don’t understand the relevance here. Second, what part of the okapilib documentation is dated? The site uses doxygen, which is an industry standard tool, and the new PROS 4 docs use it as well, and I’m reasonably certain the VEXCode API reference uses it in some manner. Doxygen is a great way to tightly couple your documentation to your project’s code, and provides a standardized and modern layout for the documentation it generates.

As for Okapilib being unintuitive for new programmers, Okapilib was never intended to be for teams just starting out with C++. Via rule G4, teams must be able to understand how the libraries they use work and explain them to judges. If a team isn’t capable of reading a C++ function prototype and understanding how to use it, how on earth would they be G4 compliant while using something like Okapilib?

@anon4126930

When I was younger, I thought that this wasn’t actually code but was some explanation on how a constructor works due to the overuse of pointers and pointer functions (and I didn’t know they were pointers at the time due to a lack of C++ knowledge).

I that instance, I think it’s fair to say that with your level of knowledge at the time, it would not have been G4 compliant to use Okapilib.

@anon4126930

Honestly primarily formatting.

There are no “formatting” differences between VEXCode V5 and VEXCode Pro V5 They use the exact same API, but with a different editor and file format.

@anon4126930

I use voltageunits because the motor spins faster with voltage and therefore is more powerful than traditional spin commands.

Spins faster? Yes
Is more powerful? No.
The built in PID on the V5 motor is plenty willing to use the full 12V available when the motor isn’t spinning at its target velocity. This means that the built in PID absolutely is capable of producing peak power output from the V5 motor (which happens when loaded to around 50-60% of rated RPM).

@anon4126930

This is a significant amount, especially for a drivetrain where competitive teams have negligible friction on their wheels, if built correctly.

Friction isn’t really the relevant factor here, especially on a drivetrain. The most important variable is how much load is on the motor, whether it comes from friction or from trying to propel a metal robot around. The most relevant use case for the extra speed voltage control gives is very low friction, high speed flywheels, where the extra 10-15% velocity can enable infrequent long range shots.

@anon4126930

On the PROS website you listed here: API Home | PROS for V5

It lists “Okapilib” and provides the following page: OkapiLib Index Page | OkapiLib A PROS library for programming VEX robots

And if you click “Tutorials” for okapilib, it goes to the ugly code, that of course isn’t maintained.

Right. @BattleCh1cken stated that Okapilib is no longer maintained. You stated that Okapilib is no longer maintained. Okapilib’s repo states that Okapilib is no longer maintained. Where is the disagreement here?

@anon4126930

As for PROS 4 documentation… It looks worse to be honest: Home » Tutorials » Walkthrough Tutorials » Programming the Clawbot | PROS for V5

This doesn’t really look like a tutorial, despite being one of the primary tutorials on the PROS page

Tutorials don’t list any examples to a degree that is fundamentally understood for newcomers:
Home » Tutorials » Topical Tutorials » ADI (3 Wire Ports) | PROS for V5

This is not really a valid example:

As noted on the front page of the PROS 4 docs:

Note

This website is for PROS 4 beta documentation and is still a heavy WIP. Expect to see bugs and rolling fixes to them. Please report any bugs to our discord.

The clawbot tutorial you’ve linked to is clearly broken and a WiP. It’s not fair to judge the docs on this page alone. Let’s take a look at an example from the docs pages that most students will be referencing regularly, the API docs:

The example given here is more than enough to understand how to use the function in question.

@anon4126930

However this is promising:
ADI (TriPort) C++ API module | PROS for V5

and a step in the right direction, but the example seems un-necessarily verbose:

#define POTENTIOMETER_PORT 1
#define POTENTIOMETER_TYPE pros::E_ADI_POT_EDR

void opcontrol() {
  pros::ADIPotentiometer potentiometer (POTENTIOMETER_PORT, POTENTIOMETER_TYPE);
  while (true) {
    // Get the potentiometer angle
    std::cout << "Angle: " << potnetiometer.get_angle();
    pros::delay(10);
  }
}

What is unnecessarily verbose about this example? I think it is a good example that also tries to demonstrate good coding practices such as the utilization of constants, and even displays the returned value so that students can see how the value displayed reacts to the potentiometer being turned. Would I write my code exactly the same way? Maybe not, but I think as an example usage for the function, this code is perfectly adequate.

@anon4126930

To put it bluntly, tutorials should assume that individuals have at least some C knowledge, but should try to understand that the vast majority of individuals have very little prior knowledge to C++. Basically, there is a threshold where teaching is more important than merely being “right.”

You are misunderstanding PROS’s target audience here. The goal of the documentation is to document how to use the PROS API. The goal is not to teach students C++ from scratch. From the PROS 4 documentation:

Learning C/C++ is essential for using PROS.

That being said, anecdotally, I came into the 2018-2019 competition year with zero C++ experience. Through trial and error, and through reading the PROS docs, with very little outside C++ reference, I was able to start my C++ learning and program my robot in C++ for that year. So, despite it not being the goal of the PROS docs, the PROS docs were sufficient to teach me enough C++ to get going with programming my robot. And for the record, so were the Okapi docs and tutorials, which again I was able to utilize to get going with Okapi despite little C++ knowledge prior. So, I disagree with your assertion that the PROS documentation is extremely unfriendly to newcomers.

@anon4126930

Simply put, good tutorials introduce more individuals into PROS, instead of being verbose right off the bar. It should have examples look more like this:

void opcontrol() {
  pros::ADIPotentiometer potentiometer (1, pros::E_ADI_POT_EDR);
  while (true) {
    double angle = potentiometer.get_angle();

    // Print the angle to the command line
    std::cout << "Angle: " << angle  << std::endl; 
    pros::delay(10);
  }
}

Now, new individuals who are learning PROS can better realize and connect the dots as to how the objects and functions work, and over time create the connection as to how PROS works fundamentally.

Then, you can explain after that it’s not necessarily C++ standard and show them the C++ standard version:

The code you’re pulling from here was in an API reference, not a tutorial. It does not make sense to have slightly different “beginner” and “advanced” examples for every function in the API reference. And again, teaching C++ from scratch is not the goal here so simply demonstrating good C++ practices in examples is more than enough.

@anon4126930

PROS intentionally tries to be difficult to understand and would rather add quantity without double checking the quality

@anon4126930

PROS decides to be non-intuitive when the vast majority of individuals simply do not have the classrooms that teach C++. Is the point of PROS to teach, or is it to close off a sector of intellectual capability to those with pre-existing knowledge?

This is an outrageous assertion, and is unbelievably insulting to the over 10 years of efforts from countless students and contributors to the PROS project. You can make statements about how one programming environment is easier to use than another, or how you prefer VEXCode over PROS, but to assert that the PROS team goes out of their way to make their project difficult for students to learn and use is an egregious overstep, and I think you owe the entire PROS team an apology for this immediately.

@anon4126930

I didn’t have the resources to adequately understand C++ to its extent

Every student here has those resources. Here you go: https://www.learncpp.com/

You don’t need to know advanced C++ to use PROS. You can get by with an incredibly basic understanding of variables, functions, and control structures which can be gleaned from the first few tutorials on that page. I know this because I and many other students I know were able to do just that.

---

Connor, you are free to guide students to use VEXCode when they ask for such guidance on this forum. You are free to list the reasons why you think VEXCode is better. It is not ok to attack the character of the PROS developers and maintainers. That is not what this competition is about, and it only serves to demotivate those who are doing their best to make things better for the students who compete in this competition. I hope you reflect on this and issue an apology to the entire PROS team promptly.