Bart Massey

You have been asked to review a project by another student or group of students or by me. This should not take long. (I expect it will take less than an hour.)

You must be polite and positive in your reviews. Criticism is not useful. Ways the project can be improved are useful. I take this very seriously. Make every comment in a good way: offer ways to make the project better. If you can't, don't make the comment at all. When things are good, say so: don't just be quiet.

These projects are not done yet. That is OK: I am asking you to look at the code as is at this point in the project.

Here's what I want you to look for:

Who and What

  • Is the project name clear?

  • Are the authors identified by name?

  • Is there some way to contact the authors?

  • Is there an easy-to-find copyright notice for the project?

  • Is there an easy-to-find and clear license for the project?

  • Can you tell what the project is trying to do?

Repo

  • Does the repo have a solid top-level README?

  • Are there binary files in the repo? (This is almost always a mistake.)

  • Are there passwords or other secrets in the repo?

  • Does the issue tracker for the repo have issues filed in it? (It is OK not to have any, but you should read them if they are there.)

  • Is the repo missing useful documentation?

Structure

  • Is the directory structure of the project clear and usable?

  • Does the project build using Cargo? Is the Cargo.toml OK?

  • Can you build the project? If not, do you know how you would build it when it is complete?

  • Can you run the project? If not, do you know how you would run it when it is complete?

Code Quality

  • Is the code format like you would expect: normal Rust format? Would rustfmt edit the code a lot?

  • Is the crate / module layout clear and usable?

  • Pick a few small sections of code.

    • Can you read the code easily? Can you tell what it is trying to do?

    • Are there good comments in the code?

    • Has Rustdoc been used to document the code? Are there tests or doctests in the code?

  • Is some of this code not written by the students? If so, does it say clearly where it came from; is this code that the students are allowed to use by license?

Completion

  • How close is this code to being done? Can it be finished in the time remaining?

  • If the code looks too far from done, what could be done to make the project simpler so that it could finish?

Other Thoughts

  • What is best about this project? What has been done well?

  • What else could be done to improve the project? Focus on things with small effort that would for sure make it better.

Last modified: Monday, 28 May 2018, 10:39 PM