Desired state of code documentation Question

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.

posted about 3 years ago

CC0

ArtOfCode‭ staff

381 reputation 1 18 39 7