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 »
Users Search
Help Dashboard Sign In Sign Up
Q&A
Q&A
Posts Tags Edits
Create Post

Comments on Desired state of code documentation

Post

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?
development comments
posted almost 3 years ago
user card
Trilarion‭
147 reputation 17 4 24 24
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)
I don't think there is code documentation
deleted user wrote almost 3 years ago
copy link

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 almost 3 years ago
copy link

@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?