Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Desired state of code documentation Question

+3
−0

Was having a look at the QPixel code base and comments in code seem to be relatively scarce. It might be that documentation about the code is stored somewhere else with Ruby or that the general level of code documentation is relatively low currently. I also know that people have quite different views on that (some like that more verbose, others more terse).

When I develop I usually try to mimmick the Java API documentation style, i.e.:

  • For every method description of parameters and contract of that method
  • For every class description of the purpose of that class
  • For every package of classes description of that package
  • Comments in code where necessary (i.e. where non-trivial things happen)
  • Maybe a high level document describing the architecture

Question(s) here would be:

  • What amount of code documentation is available for QPixel and where is it stored?
  • What amount/structure of code documentation would be desirable for such a project?
  • If desired and current state do not coincide, how can someone help to get there?
History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.
Why should this post be closed?

1 comment thread

I don't think there is code documentation (2 comments)

1 answer

+2
−0

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.

History
Why does this post require attention from curators or moderators?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »