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
Notifications
Mark all as read
Q&A

Post History

66%
+2 −0
Q&A Desired state of code documentation

1 answer  ·  posted 5mo ago by Trilarion‭  ·  last activity 5mo ago by ArtOfCode‭

#1: Initial revision by user avatar Trilarion‭ · 2021-12-10T07:38:54Z (5 months ago)
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?