Post History

Desired state of code documentation

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?