Post History

QPixel has limited code documentation. That's _partially_ by design, and partially because it often just gets missed out.

Ruby is a relatively verbose language which tries to be as self-documenting as possible by design and by convention. Rails continues that pattern. A lot of Ruby and Rails code can read almost like English, which does help in understanding what it does.

So, to answer directly:

 * **What amount of code documentation is available for QPixel and where is it stored?**  
   Limited. What documentation there is resides in the code itself, in comments.
 * **What amount/structure of code documentation would be desirable for such a project?**  
   Helpfully, "enough but not too much". Extensive documentation *does* take time, which isn't always in plentiful supply, so we tend to spend more time on getting features working and tested than on extensive code documentation. That said, we also don't _need_ huge amounts of documentation about the code itself - once you're familiar with the MVC architecture and project structure, it becomes reasonably clear what each file is responsible for.

   What we're generally looking for out of your example points is this:

    * _For every method description of parameters and contract of that method_: **no**. This _should_ be included for things like helper methods and model methods that are expected to be called in several places, but for methods that define controller actions it's unnecessary.
    * _For every class description of the purpose of that class_: **no**. Again, once you're familiar with MVC and project structure, this becomes clear, so explicitly commenting it is unnecessary.
    * _For every package of classes description of that package_: **n/a**. Ruby has the concept of "modules" instead of "packages", which are similar but slightly different, operate differently, and aren't heavily used in Rails projects.
    * _Comments in code where necessary (i.e. where non-trivial things happen)_: **yes**, absolutely. If code isn't explicit or obvious about what it does, it should be explained. This is often necessary for data structure transformations in particular, which can get fairly convoluted.
    * _Maybe a high level document describing the architecture_: **yes**, although we don't currently have one. This would be an ideal place to include information about MVC architecture and project structure to help developers familiarise themselves with the project.
    * An honourable mention for _tests_, which although not themselves documentation, do help to both define and enforce what the code is supposed to do (or not do). We do have tests, but we're only around 65-70% coverage, and we can always use more, especially for edge cases or weird behaviours.

 * **If desired and current state do not coincide, how can someone help to get there?**  
   See above for what we're looking for. Perhaps the easiest way to improve is to work on adding tests, but reading through and adding comments where necessary (particularly from the point of view of a developer new to the project) would also be helpful.