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

Desired state of code documentation Question

+2
−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?
Why does this post require moderator attention?
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)

Comments on Desired state of code documentation

I don't think there is code documentation
deleted user wrote 5 months ago:

Comments in code where necessary (i.e. where non-trivial things happen)

I don't think anyone comments in code for web designing and web development. But "comment" helps to understand code easily but web designing (excluding Ruby since it's the hardest one for web) (average code ) is understandable without comment.

What amount of code documentation is available for QPixel and where is it stored?

Is it necessary? What I know that is, a ruby programmer (I used to watch the linked video when started contributing QPixel) can understand how every pages deal?

What amount/structure of code documentation would be desirable for such a project?

That was never specific. But coder always try to complete code the short in can be. They always try to implement new features which stretches(expand) code always.

Trilarion‭ wrote 5 months ago:

@Istiak "I don't think anyone comments in code for web designing and web development." I hope that this is not (completely) true. Usually no comments does not work for more than single person projects and even for them only if they never have to look back at their code after say six months. "web designing is understandable without comment." It's programming like everything else. I wonder how it could accomplish this remarkable feature. But even then, if the code is easier to read there is still the problem with getting to know the original coders intentions (the contract of the code). Maybe they are all part of the tests?

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate